Unit test React components using Cypress

Usage no npm install needed!

<script type="module">
  import zelzCypressReactUnitTest from 'https://cdn.skypack.dev/@zelz/cypress-react-unit-test';


cypress-react-unit-test Build Status Cypress.io tests renovate-app badge This project is using Percy.io for visual regression testing.

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


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


Requires Node version 6 or above.

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

If you need help configuring bundler, see preprocessors info


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.


// 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 />
      .invoke('setState', { name: 'React' })
      .should('deep.equal', { name: 'React' })
    // check if GUI has rerendered
    cy.contains('Hello React!')

Unit testing React components


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"


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

And write a component using class properties

import React from 'react'

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

  // ...


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

Large examples


  • 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