Cypress File Upload and Download

Many web applications let users upload documents or download reports. Cypress provides commands and patterns to test both actions reliably. This topic walks through common upload and download scenarios.

Uploading a File

Cypress uses the selectFile command to simulate choosing a file for an upload field.

cy.get('#file-input').selectFile('cypress/fixtures/sample.pdf')

This line attaches the sample.pdf file located in the fixtures folder to the file input element.

A Simple Way to Picture It

Think of file upload testing as handing a folder to a receptionist at a front desk. The receptionist takes the folder and places it into the correct filing cabinet. Cypress plays the role of the person handing over the file, while your application handles storing it.

Verifying an Upload Succeeded

After selecting a file, most applications show a confirmation message or a preview of the uploaded content.

cy.get('#file-input').selectFile('cypress/fixtures/sample.pdf')
cy.contains('sample.pdf').should('be.visible')

This check confirms the application recognized and displayed the uploaded file's name.

Upload Flow Diagram

Fixture File (sample.pdf)
      |
      v
selectFile attaches it to the input
      |
      v
Application processes the upload
      |
      v
Confirmation message appears

Uploading Multiple Files

Some upload fields accept several files at once. Cypress supports this by passing an array of file paths.

cy.get('#file-input').selectFile([
  'cypress/fixtures/photo1.jpg',
  'cypress/fixtures/photo2.jpg'
])

Simulating Drag and Drop Uploads

Some upload areas only accept files through a drag and drop zone instead of a standard input field. Cypress can simulate this using the same selectFile command with a special action option.

cy.get('.drop-zone').selectFile('cypress/fixtures/sample.pdf', { action: 'drag-drop' })

Downloading Files

Cypress does not directly control the browser's native download dialog, since downloads happen outside the visible page. Instead, tests typically verify that a downloaded file exists on disk after triggering the download.

cy.get('#download-report').click()
cy.readFile('cypress/downloads/report.pdf').should('exist')

A Simple Way to Picture It

Think of a download test as checking a mailbox after expecting a package. You do not watch the delivery truck directly, but you check the mailbox afterward to confirm the package arrived. Cypress checks the downloads folder the same way, confirming the file landed successfully.

Setting a Download Folder

Cypress saves downloaded files into a folder called cypress/downloads by default. This location can be changed inside the configuration file if needed.

module.exports = defineConfig({
  downloadsFolder: 'cypress/my-downloads'
})

Verifying Downloaded File Content

Beyond checking that a file exists, some tests verify the actual content inside a downloaded file, such as a CSV report.

cy.readFile('cypress/downloads/report.csv').should('contain', 'Total Sales')

This check confirms the downloaded file contains expected data, not just an empty or corrupted file.

Cleaning Up Downloaded Files

Repeated test runs can leave old downloaded files in the downloads folder, causing confusion during verification. Many teams clear this folder before each test run using a plugin or a simple file deletion task.

Key Points

• The selectFile command simulates choosing a file for upload.
• Cypress can simulate both standard input uploads and drag and drop uploads.
• Download tests verify a file's existence in the downloads folder afterward.
• The readFile command can check both existence and content of downloaded files.
• Clearing the downloads folder before each run avoids confusion from old files.