Cypress - File Upload

Cypress - File Upload

Cypress provides native support for simulating file uploads through the .selectFile() command. This command can be used on an <input type="file"> element to trigger a file selection, just as a user would.

For most standard file upload scenarios, the built-in .selectFile() command is sufficient and recommended. Place the file you want to upload within your cypress/fixtures folder for easy access.

Using .selectFile()

The .selectFile() command can accept:

• A path to a fixture file: cy.get('input[type="file"]').selectFile('cypress/fixtures/my-image.png')
• Fixture options: cy.get('input[type="file"]').selectFile({ contents: 'cypress/fixtures/my-document.pdf', fileName: 'report.pdf', mimeType: 'application/pdf' })
• File contents (Buffer or string): cy.get('input[type="file"]').selectFile({ contents: Cypress.Buffer.from('file content'), fileName: 'example.txt', mimeType: 'text/plain' })
• An array of files for multiple file uploads (if the input supports it).

Let’s assume you have a file named avatar.png in your cypress/fixtures folder.

Implementation Example

Here’s how you can implement file upload in a Cypress test using .selectFile():

describe('File Upload Test', () => {
    it('Successfully uploads a file', () => {
        // Path to the file in the fixtures folder
        const fixtureFile = 'avatar.png';

        // Visit the page with the file upload form
        cy.visit('https://the-internet.herokuapp.com/upload');

        // Select the file using the input element's ID
        cy.get('#file-upload').selectFile(`cypress/fixtures/${fixtureFile}`);

        // Click the submit button
        cy.get('#file-submit').click();

        // Verify that the file was uploaded
        cy.get('#uploaded-files').should('contain.text', 'avatar.png');
    });
});

Execution and Output

When this test runs:

• Cypress navigates to the upload page.
• It locates the <input type="file"> element with the ID file-upload.
• The .selectFile() command attaches avatar.png from the cypress/fixtures folder to this input.
• Cypress then clicks the submit button.
• Finally, it verifies that the text ‘avatar.png’ appears in the element with ID uploaded-files, confirming the upload.

The Test Runner will show these steps, and if the upload is successful, the assertion will pass. You won’t see a native OS file dialog; Cypress handles the file attachment programmatically.

Alternative: cypress-file-upload Plugin

For older projects or very specific edge cases (like drag-and-drop uploads not directly supported by .selectFile()), the cypress-file-upload plugin was a common solution. While .selectFile() is now preferred, it’s useful to know about this plugin.

To use it, you would first install it:

npm install --save-dev cypress-file-upload

Then, import it in your cypress/support/e2e.js (or commands.js) file:

cypress/support/e2e.js

import 'cypress-file-upload';

The plugin provides an .attachFile() command, used similarly: cy.get('#file-upload').attachFile(fixtureFile);

However, always try to use the native .selectFile() command first, as it’s maintained by the Cypress team and integrated directly into the core.