@cypress/react

A little helper to unit test React components in the open source Cypress.io test runner v7.0.0+

Jump to: Comparison, Blog posts, Install, Examples: basic, advanced, full, external, Style options, Code coverage, Visual testing, Common problems, Chat

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.

• How is this different from Enzyme or RTL? It is similar in functionality BUT runs the component in the real browser with full power of Cypress E2E test runner: live GUI, full API, screen recording, CI support, cross-platform, and visual testing.
• If you like using @testing-library/react, you can use @testing-library/cypress for the same findBy, queryBy commands, see one of the examples in the list below
• Read My Vision for Component Tests in Cypress by Gleb Bahmutov

Comparison

If you are coming from Jest + RTL world, read Test The Interface Not The Implementation.

If you are coming from Enzyme world, check out the enzyme example.

Blog posts

• My Vision for Component Tests in Cypress
• Unit Testing React components with Cypress
• Test React Component with @cypress/react Example
• Tic-Tac-Toe Component Tests
• Using .env and .env.test from React component tests
• Visual testing for React components using open source tools
• 12 Recipes for testing React applications using @cypress/react (compare to 12 Recipes for testing React applications using Testing Library)
• Cypress Unit Testing React Components With TypeScript
• Test The Interface Not The Implementation compares Jest + React Testing Library to @cypress/react + Cypress Testing Library
• Components People Test about testing a component inside a Next.js-powered blog

Install

Requires Node version 12 or above.

npm install --save-dev cypress @cypress/react @cypress/webpack-dev-server

Init

You can use our command line wizard to give you instructions on configuring this plugin. It will try to determine which framework or bundling tool you are using and give you instructions on right configuration.

npx create-cypress-tests --component-tests

Or continue with manual installation in the plugin file

1. 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 (even after ejecting) do:

// cypress/plugins/index.js
module.exports = (on, config) => {
  require('@cypress/react/plugins/react-scripts')(on, config)
  // IMPORTANT to return the config object
  // with the any changed environment variables
  return config
}

See Recipes for more examples.

2. You can specify where component spec files are located. For example, to have them located in src folder use:

{
  "componentFolder": "src"
}

API

• mount is the most important function, allows to mount a given React component as a mini web application and interact with it using Cypress commands
• createMount factory function that creates new mount function with default options
• unmount removes previously mounted component, mostly useful to test how the component cleans up after itself
• mountHook mounts a given React Hook in a test component for full testing, see hooks example

Examples

import React from 'react'
import { mount } from '@cypress/react'
import { HelloWorld } from './hello-world.jsx'
describe('HelloWorld component', () => {
  it('works', () => {
    mount(<HelloWorld />)
    // now use standard Cypress commands
    cy.contains('Hello World!').should('be.visible')
  })
})

Look at the examples in cypress/component folder. Here is the list of examples showing various testing scenarios.

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.

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-example

Options

In most cases, the component already imports its own styles, thus it looks "right" during the test. If you need another CSS, the simplest way is to import it from the spec file:

// src/Footer.spec.js
import './styles/main.css'
import Footer from './Footer'
it('looks right', () => {
  // styles are applied
  mount(<Footer />)
})

Extra styles

You can pass additional styles, css files and external stylesheets to load, see docs/styles.md for the full list of options.

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',
  ],
})

{
  "env": {
    "@cypress/react": {
      "react": "node_modules/react/umd/react.development.js",
      "react-dom": "node_modules/react-dom/umd/react-dom.development.js"
    }
  }
}

You may also specify the ReactDOM package to use. This can be useful in complex monorepo setups that have different versions of React and React DOM installed. If you see an error relating to mismatching versions of React or React DOM, this may be the solution. You can do this using the ReactDom option:

// if you have multiple versions of ReactDom in your monorepo
import ReactDom from 'react-dom'

mount(<Todo todo={todo} />, {
  stylesheets: [
    'https://cdnjs.cloudflare.com/ajax/libs/bulma/0.7.2/css/bulma.css',
  ],
  ReactDom
})

Code coverage

In order to use code coverage you can follow the instructions from docs. In most of cases you need to install 2 dependencies:

npm i @cypress/code-coverage babel-plugin-istanbul

yarn add @cypress/code-coverage babel-plugin-istanbul

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 Cypress Visual Testing plugin to perform visual testing from the component tests. This repo has several example projects, see visual-sudoku, visual-testing-with-percy, visual-testing-with-happo, and visual-testing-with-applitools.

For a larger Do-It-Yourself example with an hour long list of explanation videos, see bahmutov/sudoku repository. I explain how to write visual testing using open source tools in this blog post, video talk, and slides.

Common problems

const mock = jest.fn()
// render a component that does NOT allow any click events
// using pointerEvents: "none" style
const { getByRole } = render(
  <button style={{ pointerEvents: 'none' }} onClick={mock}>
    text
  </button>,
)
// Jest happily clicks
fireEvent.click(getByRole('button'))
expect(mock).not.toBeCalled()

Context Provider usage

React context provider usage and API described in ./docs/providers-and-composition.md

Chat

Come chat with us on discord in the #component-testing channel.

Development

See docs/development.md

Debugging

You can see verbose logs from this plugin by running with environment variable

DEBUG=@cypress/react

Because finding and modifying Webpack settings while running this plugin is done by find-webpack module, you might want to enable its debug messages too.

DEBUG=@cypress/react,find-webpack

Changelog

Changelog

Related tools

Same feature for unit testing components from other frameworks using Cypress

• @cypress/vue
• cypress-cycle-unit-test
• cypress-svelte-unit-test
• @cypress/angular
• cypress-hyperapp-unit-test
• cypress-angularjs-unit-test