Introduction

Handling file uploads and downloads are common scenarios in end-to-end testing. In this post, we will explore how to handle both file uploads and downloads using Cypress. Even though Cypress lacks built-in support for these operations, you can achieve this functionality by leveraging a few libraries and Cypress’s robust set of commands.

By the end of this guide, you'll know how to:

• Upload files using Cypress.
• Validate successful file uploads.
• Download files and validate their content in Cypress.

Prerequisites

To follow along with the examples, ensure you have Cypress installed and set up. If you're using Cypress v13.6.2, it’s compatible with the approaches shown in this post.

File Uploads in Cypress

To upload files in Cypress, we’ll use the cypress-file-upload plugin, which provides an easy way to simulate file upload actions during your tests.
Step 1: Install cypress-file-upload Plugin
To handle file uploads in Cypress, you’ll first need to install the cypress-file-upload package.

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

Next, import it in your commands.js file inside the Cypress support folder:

import 'cypress-file-upload';

Step 2: Folder Structure
Ensure your project has the following folder structure to store test files and upload them during the tests:

cypress/
    fixtures/
        exampleFile.pdf  // Test file for uploading
    e2e/
        fileUploadTests.cy.js  // Test file to upload and validate

Step 3: Uploading a File
Once you have the plugin installed, you can use the attachFile command to upload a file from the fixtures folder.

Here’s how you can upload a file:

describe('File Upload Test in Cypress', () => {
  it('should upload a file successfully', () => {
    // Visit the page with a file upload input
    cy.visit('/upload');

    // Select the file input element and upload a file from the fixtures folder
    cy.get('input[type="file"]').attachFile('exampleFile.pdf');

    // Validate that the file was uploaded (depends on your app's specific response)
    cy.get('.file-name').should('contain', 'exampleFile.pdf');
  });
});

In this test:

• We visit the page where the file input exists.
• We use attachFile() to simulate the file upload from the fixtures folder.
• The assertion checks whether the uploaded file’s name appears correctly on the page.

Validating File Uploads

Validating a file upload can be as simple as checking whether the file name or path appears on the webpage after the upload. However, for complex scenarios (e.g., verifying file content or size), you might need server-side checks or stubs.

Example: Validate File Upload with Additional Data

describe('File Upload and Validation', () => {
  it('should upload a file and validate metadata', () => {
    cy.visit('/upload');

    cy.get('input[type="file"]').attachFile('exampleFile.pdf');

    // Assert that the file metadata like size is displayed correctly
    cy.get('.file-size').should('contain', 'Size: 1MB');
  });
});

File Downloads in Cypress
Cypress doesn’t provide native support for verifying file downloads (since the browser downloads files outside of Cypress’s control), but we can work around this by directly checking the downloaded file in the local file system.

Step 1: Installing cypress-downloadfile
To validate file downloads in Cypress, we can use the cypress-downloadfile plugin.

Install it via npm:

npm install --save-dev cypress-downloadfile

Next, add the plugin to your commands.js file:

require('cypress-downloadfile/lib/downloadFileCommand');

Step 2: Downloading and Validating Files
You can now write a test that downloads a file and verifies its content.

Example: Downloading a File

describe('File Download Test in Cypress', () => {
  it('should download a file and validate its content', () => {
    cy.visit('/download');

    // Download the file and save it to a custom downloads folder
    cy.downloadFile('https://example.com/sample.pdf', 'cypress/downloads', 'sample.pdf');

    // Validate that the file exists in the specified location
    cy.readFile('cypress/downloads/sample.pdf').should('exist');
  });
});

In this test:

• We use cy.downloadFile() to download a file from a URL and store it in the cypress/downloads folder.
• After the download, we validate that the file exists using cy.readFile().

Step 3: Validating File Content
You may want to verify the content of the downloaded file to ensure the download was successful. For text-based files (e.g., .txt, .csv), Cypress’s cy.readFile() can be used to assert the file’s content.

Example: Validate Downloaded File Content

describe('Validate Downloaded File Content', () => {
  it('should download and check the content of a text file', () => {
    cy.visit('/download');

    // Download the text file
    cy.downloadFile('https://example.com/sample.txt', 'cypress/downloads', 'sample.txt');

    // Read the file and assert its content
    cy.readFile('cypress/downloads/sample.txt').then((fileContent) => {
      expect(fileContent).to.contain('This is a sample text file');
    });
  });
});

This test downloads a .txt file and checks that it contains the expected text.

Best Practices for File Upload and Download in Cypress

1. Use Fixtures for Upload: Always store files for uploading in the fixtures folder to keep your test data organized and accessible.
2. Clean Up Downloads Folder: Before starting new tests, clean up the downloads folder to avoid issues with leftover files from previous test runs.
3. Verify Server Response: For file uploads, always verify server-side responses in addition to UI assertions to ensure the file is properly processed.
4. Use Temporary Directories for Downloads: Store downloaded files in temporary directories (cypress/downloads) to avoid cluttering your project structure.
5. Mock File Uploads (Optional): In scenarios where you want to mock file uploads for performance reasons, use stubs to bypass real file uploads.

Conclusion

File upload and download are critical operations in web application testing, and while Cypress doesn’t natively support these operations, the cypress-file-upload and cypress-downloadfile plugins provide easy-to-use workarounds.

In this guide, we explored how to:

• Upload files using Cypress’s cypress-file-upload plugin.
• Validate file uploads by checking file names and metadata.
• Download files using the cypress-downloadfile plugin and validate the existence and content of the downloaded files.

With these tools and techniques, you can confidently handle file uploads and downloads in your Cypress end-to-end tests!