cypress-file-upload

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 you HTML controls and focus on testing the functionality.

Table of Contents

• Installation
• Usage
• API
• Caveats
• It isn't working! What else can I try?
• Contributors
• License

Installation

The package is distributed via npm should be installed as one of your project's devDependencies:

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

Usage

cypress-file-upload extends Cypress' cy command. Add this line to your project's cypress/support/commands.js:

import 'cypress-file-upload';

Here is a basic example:

const fileName = 'data.json';

cy.fixture(fileName).then(fileContent => {
  cy.get('[data-cy="dropzone"]').upload(
    { fileContent, fileName, mimeType: 'application/json' },
    { subjectType: 'drag-n-drop' },
  );
});

If you're trying to upload a file that does not supported by default, here is the workflow:

• If a workaround with encoding does not work properly,

See more usage guidelines in example.

API

Exposed command in a nutshell:

cySubject.upload(fileOrArray, processingOpts);

fileOrArray is an object (or an array of those) that represents file information and contains following properties:

• {String} fileContent – raw file content, usually a value obtained from cy.fixture
• {String} fileName – file name (with extension)
• {String} mimeType – file mime type
• {String} encoding – (optional) normally cy.fixture resolves encoding automatically, but in case you've specified it, make sure to provide it here as well

processingOpts contains following properties:

• {String} subjectType – target (aka subject) element kind: 'drag-n-drop' component or plain HTML 'input' element. Defaults to 'input'
• {Boolean} force – (optional) same as for cy.trigger it enforces events triggering on HTML subject element. Usually this is necessary when you use hidden HTML controls for your file upload. Defaults to false

Caveats

During the lifetime plugin faced the following issues those you should 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

It isn't working! What else can I try?

What to do in case if the plugin is not working for you? Here are some steps:

1. Check Caveats – maybe there is a tricky thing about exactly your issue
2. Submit the issue and let us know about you problem
3. In case you're using a file with encoding and/or extension that is not yet supported, make sure you've tried to explicitly set the encoding property (see API)
4. State what you experience using the workaround above as well

Contributors

Thanks goes to these wonderful people (emoji key):

James Hollowell 💻	lunxiao 🐛	Oliver O'Donnell 🐛 💻	Peter Colapietro 📖	km333 🐛	Kevin Mui 💻 🤔 👀	Ben Wurth 🐛 💻
Andreev Sergey ⚠️ 💬 💡 💻	Guts 💬	maple-leaf 💬 💻	Daniel Mendalka 💬	Chris Sargent 💬	Ronak Chovatiya 💬	Jan Hesters 💬 🐛
John Molakvoæ 💬	Phil Jones 🐛	Nicolas Gehring 🐛	David Pertiller 💬

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT