Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/abramenal/cypress-file-upload

File upload testing made easy
https://github.com/abramenal/cypress-file-upload
cypress cypress-file-upload cypress-io cypress-plugin cypressio cypressjs
Last synced: about 2 months ago
JSON representation
File upload testing made easy
Host: GitHub
URL: https://github.com/abramenal/cypress-file-upload
Owner: abramenal
License: mit
Created: 2019-01-25T11:53:01.000Z (over 5 years ago)
Default Branch: main
Last Pushed: 2023-05-30T12:48:40.000Z (over 1 year ago)
Last Synced: 2024-07-21T11:03:07.690Z (2 months ago)
Topics: cypress, cypress-file-upload, cypress-io, cypress-plugin, cypressio, cypressjs
Language: JavaScript
Homepage: https://npm.im/cypress-file-upload
Size: 1.59 MB
Stars: 496
Watchers: 9
Forks: 89
Open Issues: 35
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # cypress-file-upload

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/abramenal/cypress-file-upload/blob/master/LICENSE) [![npm version](https://img.shields.io/npm/v/cypress-file-upload.svg?style=flat&color=red)](https://www.npmjs.com/package/cypress-file-upload) ![build](https://github.com/abramenal/cypress-file-upload/workflows/build/badge.svg) [![All Contributors](https://img.shields.io/badge/all_contributors-33-yellow.svg?style=flat&color=9cf)](#contributors) [![monthly downloads](https://img.shields.io/npm/dm/cypress-file-upload.svg?style=flat&color=orange&label=monthly%20downloads)](https://www.npmjs.com/package/cypress-file-upload) [![downloads all time](https://img.shields.io/npm/dt/cypress-file-upload.svg?style=flat&color=black&label=lifetime%20downloads)](https://www.npmjs.com/package/cypress-file-upload)

File upload testing made easy.

This package adds a custom [Cypress][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

- [Installation](#installation)

- [Usage](#usage)

  - [HTML5 file input](#html5-file-input)

  - [Drag-n-drop component](#drag-n-drop-component)

  - [Attaching multiple files](#attaching-multiple-files)

  - [Working with file encodings](#working-with-file-encodings)

  - [Working with raw file contents](#working-with-raw-file-contents)

  - [Override the file name](#override-the-file-name)

  - [Working with empty fixture file](#working-with-empty-fixture-file)

  - [I wanna see some real-world examples](#i-wanna-see-some-real-world-examples)

- [API](#api)

- [Recipes](#recipes)

- [Caveats](#caveats)

- [It isn't working! What else can I try?](#it-isnt-working-what-else-can-i-try)

- [Contributors](#contributors)

- [License](#license)

## Installation

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

```bash

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

```

If you are using TypeScript, ensure your `tsconfig.json` contains commands' types:

```json

"compilerOptions": {

  "types": ["cypress", "cypress-file-upload"]

}

```

To be able to use any custom command you need to add it to `cypress/support/commands.js` like this:

```javascript

import 'cypress-file-upload';

```

Then, make sure this `commands.js` is imported in `cypress/support/index.js` (it might be commented):

```javascript

// Import commands.js using ES2015 syntax:

import './commands';

```

All set now! :boom:

## Usage

Now, let's see how we can actually test something. Exposed command has signature like:

```javascript

cySubject.attachFile(fixture, optionalProcessingConfig);

```

It is a common practice to put all the files required for Cypress tests inside `cypress/fixtures` folder and call them as fixtures (or a fixture).  The command recognizes [`cy.fixture`][cy.fixture] format, so usually this is just a file name.

### HTML5 file input

```javascript

cy.get('[data-cy="file-input"]')

  .attachFile('myfixture.json');

```

### Drag-n-drop component

```javascript

cy.get('[data-cy="dropzone"]')

  .attachFile('myfixture.json', { subjectType: 'drag-n-drop' });

```

### Attaching multiple files

```javascript

cy.get('[data-cy="file-input"]')

  .attachFile(['myfixture1.json', 'myfixture2.json']);

```

_Note: in previous version you could also attach it chaining the command. It brought flaky behavior with redundant multiple event triggers, and was generally unstable. It might be still working, but make sure to use array instead._

### Working with file encodings

In some cases you might need more than just plain JSON [`cy.fixture`][cy.fixture]. If your file extension is supported out of the box, it should all be just fine.

In case your file comes from some 3rd-party tool, or you already observed some errors in console, you likely need to tell Cypress how to treat your fixture file.

```javascript

cy.get('[data-cy="file-input"]')

  .attachFile({ filePath: 'test.shp', encoding: 'utf-8' });

```

**Trying to upload a file that does not supported by Cypress by default?** Make sure you pass `encoding` property (see [API](#api)).

### Working with raw file contents

Normally you do not need this. But what the heck is normal anyways :neckbeard:

If you need some custom file preprocessing, you can pass the raw file content:

```javascript

const special = 'file.spss';

cy.fixture(special, 'binary')

  .then(Cypress.Blob.binaryStringToBlob)

  .then(fileContent => {

    cy.get('[data-cy="file-input"]').attachFile({

      fileContent,

      filePath: special,

      encoding: 'utf-8',

      lastModified: new Date().getTime()

    });

  });

```

You still need to provide `filePath` in order to get file's metadata and encoding. For sure this is optional, and you can do it manually:

```javascript

cy.fixture('file.spss', 'binary')

  .then(Cypress.Blob.binaryStringToBlob)

  .then(fileContent => {

    cy.get('[data-cy="file-input"]').attachFile({

      fileContent,

      fileName: 'whatever',

      mimeType: 'application/octet-stream',

      encoding: 'utf-8',

      lastModified: new Date().getTime(),

    });

  });

```

### Override the file name

```javascript

cy.get('[data-cy="file-input"]')

  .attachFile({ filePath: 'myfixture.json', fileName: 'customFileName.json' });

```

### Working with empty fixture file

Normally you have to provide non-empty fixture file to test something. If your case isn't normal in that sense, here is the code snippet for you:

```javascript

cy.get('[data-cy="file-input"]')

  .attachFile({ filePath: 'empty.txt', allowEmpty: true });

```

### Waiting for the upload to complete

Cypress' [`cy.wait`][cy.wait] command allows you to pause code execution until some asyncronous action is finished. In case you are testing file upload, you might want to wait until the upload is complete:

```javascript

// start watching the POST requests

cy.server({ method:'POST' });

// and in particular the one with 'upload_endpoint' in the URL

cy.route({

  method: 'POST',

  url: /upload_endpoint/

}).as('upload');

const fileName = 'upload_1.xlsx';

cy.fixture(fileName, 'binary')

    .then(Cypress.Blob.binaryStringToBlob)

    .then(fileContent => {

      cy.get('#input_upload_file').attachFile({

        fileContent,

        fileName,

        mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',

        encoding:'utf8',

        lastModified: new Date().getTime()

      })

    })

// wait for the 'upload_endpoint' request, and leave a 2 minutes delay before throwing an error

cy.wait('@upload', { requestTimeout: 120000 });

// stop watching requests

cy.server({ enable: false })

// keep testing the app

// e.g. cy.get('.link_file[aria-label="upload_1"]').contains('(xlsx)');

```

### I wanna see some real-world examples

There is a set of [recipes](./recipes) that demonstrates some framework setups along with different test cases. Make sure to check it out when in doubt.

## API

Exposed command in a nutshell:

```javascript

cySubject.attachFile(fixture, processingOpts);

```

**Familiar with TypeScript?** It might be easier for you to just look at [type definitions](./types/index.d.ts).

`fixture` can be a string path (or array of those), or object (or array of those) that represents your local fixture file and contains following properties:

- {string} `filePath` - file path (with extension)

- {string} `fileName` - the name of the file to be attached, this allows to override the name provided by `filePath`

- {Blob} `fileContent` - the binary content of the file to be attached

- {string} `mimeType` - file [MIME][mime] type. By default, it gets resolved automatically based on file extension. Learn more about [mime](https://github.com/broofa/node-mime)

- {string} `encoding` - normally [`cy.fixture`][cy.fixture] resolves encoding automatically, but in case it cannot be determined you can provide it manually. For a list of allowed encodings, see [here](https://github.com/abramenal/cypress-file-upload/blob/master/lib/file/constants.js#L1)

- {number} `lastModified` - The unix timestamp of the lastModified value for the file.  Defaults to current time. Can be generated from `new Date().getTime()` or `Date.now()`

`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` - same as for [`cy.trigger`][cy.trigger], it enforces the event triggers on HTML subject element. Usually this is necessary when you use hidden HTML controls for your file upload. Defaults to `false`

- {boolean} `allowEmpty` - when true, do not throw an error if `fileContent` is zero length. Defaults to `false`

## Recipes

There is a set of [recipes](./recipes) that demonstrates some framework setups along with different test cases. Make sure to check it out when in doubt.

Any contributions are welcome!

## Caveats

During the lifetime plugin faced some issues you might need to be aware of:

- Chrome 73 changes related to HTML file input behavior: [#34][#34]

- Force event triggering (same as for [`cy.trigger`][cy.trigger]) should happen when you use hidden HTML controls: [#41][#41]

- Binary fixture has a workarounded encoding: [#70][#70]

- Video fixture has a workarounded encoding: [#136][#136]

- XML encoded files: [#209][#209]

- Shadow DOM compatibility: [#74][#74]

- Reading file content after upload: [#104][#104]

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

Here is step-by-step guide:

1. Check [Caveats](#caveats) - maybe there is a tricky thing about exactly your setup

1. Submit the issue and let us know about you problem

1. 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 `encoding` property (see [API](#api))

1. Comment your issue describing what happened after you've set the `encoding`

## I want to contribute

You have an idea of improvement, or some bugfix, or even a small typo fix? That's :cool:

We really appreciate that and try to share ideas and best practices. Make sure to check out [CONTRIBUTING.md](./CONTRIBUTING.md) before start!

Have something on your mind? Drop an issue or a message in [Discussions](https://github.com/abramenal/cypress-file-upload/discussions).

## Contributors

Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#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}
💬 💻

    
_Amy
🐛

    
_{Tomasz Szymczyszyn}
📖

    
_nitzel
💻

  

  

    
_dirk
🤔

    
_{Addie Morrison}
🐛

    
_{Alec Brunelle}
🐛

    
_{Gleb Bahmutov}
🤔

    
_{Jesse de Bruijne}
📖

    
_{Justin Littman}
💬

    
_harrison9149
🐛

  

  

    
_jdcl32
💬 💻

    
_{David Sheldrick}
💻

    
_{Tom MacWright}
💻

    
_{Andrew Hoddinott}
💻

    
_{Eneko Rodríguez}
💻

    
_{Dmitry Nikulin}
💻

    
_{Thiago Brezinski}
🐛

  

  

    
_Jack
💬

    
_{Yoni Gibbs}
🐛

    
_{benowenssonos}
🐛

    
_Aymeric
💬

    
_{Alfredo Sumaran}
🐛

    
_x-yuri
🤔

    
_{Tri Q. Tran}
💻

  

  

    
_{Francis Chartrand}
📖

    
_{Emil Ong}
💻

    
_Evgenii
📖

    
_{Joseph Zidell}
🚧

    
_{Daniel Caballero}
💻

    
_{Adrien Joly}
📖

    
_{Jayson Harshbarger}
💻

  

  

    
_Andrico
📖

    
_{Paul Blyth}
💻

    
_{Justin Bennett}
📖

    
_{Shafiq Jetha}
📖

    
_{tt rt}
💻

    
_{Ed Hollinghurst}
📖

    
_anark
⚠️ 💻

  

  

    
_{Michael Altamirano}
💻 💬

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

## License

[MIT][mit]

[cypress]: https://cypress.io/

[cy.fixture]: https://docs.cypress.io/api/commands/fixture.html

[cy.trigger]: https://docs.cypress.io/api/commands/trigger.html#Arguments

[cy.wait]: https://docs.cypress.io/api/commands/wait.html

[npm]: https://www.npmjs.com/

[mime]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types

[mit]: https://opensource.org/licenses/MIT

[#34]: https://github.com/abramenal/cypress-file-upload/issues/34

[#41]: https://github.com/abramenal/cypress-file-upload/issues/41

[#70]: https://github.com/abramenal/cypress-file-upload/issues/70

[#74]: https://github.com/abramenal/cypress-file-upload/issues/74

[#104]: https://github.com/abramenal/cypress-file-upload/issues/104

[#136]: https://github.com/abramenal/cypress-file-upload/issues/136

[#209]: https://github.com/abramenal/cypress-file-upload/issues/209