File upload testing made easy.
This package adds a custom Cypress command that allows you to make an abstraction on how exactly you upload files through HTML controls and focus on testing user workflows.
Table of Contents
The package is distributed via npm and should be installed as one of your project's
npm install --save-dev cypress-file-upload
cypress-file-upload extends Cypress'
Add this line to your project's
Now you are ready to actually test uploading. Here are some basic examples:
/* Plain HTML input */const yourFixturePath = 'data.json';cy;/* Drag-n-drop component */cy;/* You can also attach multiple files by chaining the command */const yourBestPicture = 'meow.png';cy;/* If your file encoding is not supported out of the box, make sure to pass it explicitly */const weirdo = 'test.shp';cy;/* If your input element is invisible or stays within shadow DOM, make sure enforcing manual event triggering */cy;/* If you want to overwrite the file name */const data = 'test.json';cy;/* If your file needs special processing not supported out of the box, you can pass fileContent directly */const special = 'file.spss';cy/* when providing fileContent is possible to ignore filePath but fileName and mime type must be provided */const special = 'file.spss';cy
Trying to upload a file that does not supported by Cypress by default? Make sure you pass
encoding property (see API).
See more usage guidelines in recipes.
Exposed command in a nutshell:
fixture is a string path (or object with same purpose) that represents your local fixture file and contains following properties:
filePath– file path (with extension)
fileName- (optional) the name of the file to be attached, this allows to override the name provided by
fileContent- (optional) the binary content of the file to be attached
mimeType– (optional) file MIME type. By default, it gets resolved automatically based on file extension. Learn more about mime
encoding– (optional) normally
cy.fixtureresolves encoding automatically, but in case it cannot be determined you can provide it manually. For a list of allowed encodings, see here
processingOpts (optional) contains following properties:
subjectType– target (aka subject) element kind:
'drag-n-drop'component or plain HTML
'input'element. Defaults to
force– (optional) same as for
cy.triggerit enforces events triggering on HTML subject element. Usually this is necessary when you use hidden HTML controls for your file upload. Defaults to
allowEmpty- (optional) when true, do not throw an error if
fileContentis zero length. Defaults to
Most common frontend UI setups along with Cypress & file upload testing are located at recipes.
Any contributions are welcome!
During the lifetime plugin faced some issues you might need to be aware of:
- Chrome 73 changes related to HTML file input behavior: #34
- Force event triggering (same as for
cy.trigger) should happen when you use hidden HTML controls: #41
- Binary fixture has a workarounded encoding: #70
- Video fixture has a workarounded encoding: #136
- Shadow DOM compatibility: #74
- Reading file content after upload: #104
It isn't working! What else can I try?
Here is step-by-step guide:
- Check Caveats – maybe there is a tricky thing about exactly your setup
- Submit the issue and let us know about you problem
- In case you're using a file with encoding and/or extension that is not yet supported by Cypress, make sure you've tried to explicitly set the
encodingproperty (see API)
- Comment your issue describing what happened after you've set the
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!