cypress-react-unit-test
A little helper to unit test React components in the open source Cypress.io E2E test runner v4.5.0+
Jump to: Comparison, Install, Examples: basic, advanced, full, external, Options, Code coverage, Visual testing, Commoon problems
TLDR
- What is this? This package allows you to use Cypress test runner to unit test your React components with zero effort. Here is a typical component testing, notice there is not external URL shown, since it is mounting the component directly.
Comparison
Feature | Jest / Enzyme / RTL | Cypress + cypress-react-unit-test |
---|
Test runs in real browser | ❌ | ✅ |
Uses full mount | ❌ | ✅ |
Test speed | 🏎 | as fast as the app works in the browser |
Test can use additional plugins | maybe | use any Cypress plugin |
Test can interact with component | synthetic limited API | use any Cypress command |
Test can be debugged | via terminal and Node debugger | use browser DevTools |
Built-in time traveling debugger | ❌ | Cypress time traveling debugger |
Re-run tests on file or test change | ✅ | ✅ |
Test output on CI | terminal | terminal, screenshots, videos |
Tests can be run in parallel | ✅ | ✅ via parallelization |
Test against interface | if using @testing-library/react | ✅ and can use @testing-library/cypress |
Spying and mocking | Jest mocks | Sinon library |
Code coverage | ✅ | ✅ |
Known problems
See issues labeled v4
Install
Requires Node version 8 or above.
npm install --save-dev cypress cypress-react-unit-test
- Include this plugin from your project's
cypress/support/index.js
require('cypress-react-unit-test/support')
- Tell Cypress how your React application is transpiled or bundled (using Webpack), so Cypress can load your components. For example, if you use
react-scripts
do:
module.exports = (on, config) => {
require('cypress-react-unit-test/plugins/react-scripts')(on, config)
return config
}
See Recipes for more examples.
- ⚠️ Turn the experimental component support on in your
cypress.json
. You can also specify where component spec files are located. For example, to have them located in src
folder use:
{
"experimentalComponentTesting": true,
"componentFolder": "src"
}
Examples
import React from 'react'
import { mount } from 'cypress-react-unit-test'
import { HelloWorld } from './hello-world.jsx'
describe('HelloWorld component', () => {
it('works', () => {
mount(<HelloWorld />)
cy.contains('Hello World!').should('be.visible')
})
})
Look at the examples in cypress/component folder. Here is the list in progress
Basic examples
plus a few smaller sanity specs in cypress/component/basic folder.
Advanced examples
Full examples
We have several subfolders in examples folder that have complete projects with just their dependencies installed in the root folder.
Folder Name | Description |
---|
react-scripts | A project using react-scripts with component tests in src folder |
react-scripts-folder | A project using react-scripts with component tests in cypress/component |
webpack-options | Using the default Webpack options from @cypress/webpack-preprocessor to transpile JSX specs |
External examples
This way of component testing has been verified in a number of forked 3rd party projects.
To find more examples, see GitHub topic cypress-react-unit-test-example
Options
You can pass additional styles, css files and external stylesheets to load, see docs/styles.md for full list.
const todo = {
id: '123',
title: 'Write more tests',
}
mount(<Todo todo={todo} />, {
stylesheets: [
'https://cdnjs.cloudflare.com/ajax/libs/bulma/0.7.2/css/bulma.css',
],
})
Additional configuration
If your React and React DOM libraries are installed in non-standard paths (think monorepo scenario), you can tell this plugin where to find them. In `cypress.json` specify paths like this:
{
"env": {
"cypress-react-unit-test": {
"react": "node_modules/react/umd/react.development.js",
"react-dom": "node_modules/react-dom/umd/react-dom.development.js"
}
}
}
Code coverage
If you are using plugins/cra-v3 it instruments the code on the fly using babel-plugin-istanbul
and generates report using dependency cypress-io/code-coverage (included). If you want to disable code coverage instrumentation and reporting, use --env coverage=false
or CYPRESS_coverage=false
or set in your cypress.json
file
{
"env": {
"coverage": false
}
}
Visual testing
You can use any Visual Testing plugin from these component tests. This repo uses Percy.io visual diffing service as a GitHub pull request check.
Common problems
Node Sass
When using Node Sass styles, tell Cypress to use the system NodeJS rather than its bundled version. In cypress.json
set option:
{
"nodeVersion": "system"
}
Slow bundling
When you bundle spec file, you are now bundling React, Read DOM and other libraries, which is might be slow. For now, you can disable inline source maps by adding to your Webpack config settings (if available) the following:
const webpackOptions = {
devtool: false,
}
Keep your eye on issue #156 for more information.
Development
See docs/development.md
Migration guide
From v3 to v4
The old v3 master
branch is available as branch v3
- the
cy.mount
is now simply import { mount } from 'cypress-react-unit-test'
- the support file is simply
require('cypress-react-unit-test/support')
Related tools
Same feature for unit testing components from other frameworks using Cypress