cypress-react-unit-test

A little helper to unit test React components in the open source Cypress.io E2E test runner ALPHA

TLDR

What is this? This package allows you to use Cypress test runner to unit test your React components with zero effort.
How is this different from Enzyme? 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.

Known problems

some DOM events are not working when running all tests at once #4
cannot mock server XHR for injected components #5
cannot spy on window.alert #6

Install

Requires Node version 6 or above.

npm install --save-dev cypress cypress-react-unit-test

If you need help configuring bundler, see preprocessors info

Use

Include this plugin from cypress/support/index.js

import 'cypress-react-unit-test'

This adds a new command cy.mount that can mount a React component. It also overloads cy.get to accept in addition to selectors React component, returning it. See examples below.

Example

// load Cypress TypeScript definitions for IntelliSense
/// <reference types="cypress" />
// import the component you want to test
import { HelloState } from '../../src/hello-x.jsx'
import React from 'react'
describe('HelloState component', () => {
  it('works', () => {
    // mount the component under test
    cy.mount(<HelloState />)
    // start testing!
    cy.contains('Hello Spider-man!')
    // mounted component can be selected via its name, function, or JSX
    // e.g. '@HelloState', HelloState, or <HelloState />
    cy.get(HelloState)
      .invoke('setState', { name: 'React' })
    cy.get(HelloState)
      .its('state')
      .should('deep.equal', { name: 'React' })
    // check if GUI has rerendered
    cy.contains('Hello React!')
  })
})

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"
    }
  }
}

Transpilation

How can we use features that require transpilation? Using @cypress/webpack-preprocessor. You can use cypress/plugins/index.js to configure any transpilation plugins you need.

For example, to enable class properties:

// cypress/plugins/index.js
const webpack = require('@cypress/webpack-preprocessor')
const webpackOptions = {
  module: {
    rules: [
      {
        test: /\.(js|jsx|mjs)$/,
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env', '@babel/preset-react'],
          plugins: ['@babel/plugin-proposal-class-properties'],
        },
      }
    ]
  }
}

const options = {
  // send in the options from your webpack.config.js, so it works the same
  // as your app's code
  webpackOptions,
  watchOptions: {}
}

module.exports = on => {
  on('file:preprocessor', webpack(options))
}

Install dev dependencies

npm i -D @cypress/webpack-preprocessor \
  babel-loader @babel/preset-env @babel/preset-react \
  @babel/plugin-proposal-class-properties

And write a component using class properties

import React from 'react'

export class Transpiled extends React.Component {
  state = {
    count: 0
  }

  // ...
}

Examples

All components are in src folder. All tests are in cypress/integration folder.

hello-world-spec.js - testing the simplest React component from hello-world.jsx
hello-x-spec.js - testing React component with props and state hello-x.jsx
counter-spec.js clicks on the component and confirms the result
stateless-spec.js shows testing a stateless component from stateless.jsx
transpiled-spec.js shows testing a component with class properties syntax from transpiled.jsx
error-boundary-spec.js shows testing a component acting as an error boundary from error-boundary.jsx
users-spec.js shows how to observe XHR requests, mock server responses for component users.jsx
alert-spec.js shows how to spy on window.alert calls from your component stateless-alert.jsx

Large examples

bahmutov/calculator tests multiple components: calculator App, Button, Display.

Development

To get started with this repo, compile the plugin's code and the examples code

npm run transpile
npm run build
npm run cy:open

run TypeScript compiler in watch mode with npx tsc -w
run Cypress with npx cypress open and select the spec you want to work with
edit lib/index.ts where all the magic happens

Visual testing

Uses Percy.io visual diffing service as a GitHub pull request check.

Related tools

Same feature for unit testing components from other frameworks using Cypress

gcoombe/cypress-react-unit-test