React Component Testing

Framework Support

Cypress Component Testing currently supports React 16+ with the following frameworks:

Tutorial

Visit the React Quickstart Guide for a step-by-step tutorial on creating a new React app and adding component tests.

Installation

To get up and running with Cypress Component Testing in React, install Cypress into your project:

npm i cypress -D

Open Cypress:

npx cypress open
Choose Component Testing

Choose Component Testing

The Cypress Launchpad will guide you through configuring your project.

Framework Configuration

Cypress Component Testing works out of the box with Create React App, Next.js, Vite, and a custom Webpack config. Cypress will automatically detect one of these frameworks during setup and configure them properly. The examples below are for reference purposes.

Create React App (CRA)

Cypress Component Testing works with CRA 4+.

CRA Configuration

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'create-react-app',
      bundler: 'webpack',
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'create-react-app',
      bundler: 'webpack',
    },
  },
})

Sample Create React Apps

Next.js

Cypress Component Testing works with Next.js 11+.

Next.js Configuration

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'next',
      bundler: 'webpack',
    },
  },
})

Next.js Caveats

There are some specific caveats to consider when testing Next.js Pages in component testing.

A page component could have additional logic in its getServerSideProps or getStaticProps methods. These methods only run on the server, so they are not available to run inside a component test. Trying to test a page in a component test would result in the props being passed into the page to be undefined.

While you could pass in props directly to the page component in a component test, that would leave these server-side methods untested. However, an end-to-end test would execute and test a page entirely.

Because of this, we recommend using E2E Testing over Component Testing for Next.js pages and Component Testing for individual components in a Next.js app.

Sample Next.js Apps

React with Vite

Cypress Component Testing works with React apps that use Vite 2+ as the bundler.

Vite Configuration

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
      // optionally pass in vite config
      viteConfig: require('./vite.config'),
      // or a function - the result is merged with
      // any `vite.config` file that is detected
      viteConfig: async () => {
        // ... do things ...
        const modifiedConfig = await injectCustomConfig(baseConfig)
        return modifiedConfig
      },
    },
  },
})

import { defineConfig } from 'cypress'
import customViteConfig from './customConfig'

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
      // optionally pass in vite config
      viteConfig: customViteConfig,
      // or a function - the result is merged with
      // any `vite.config` file that is detected
      viteConfig: async () => {
        // ... do things ...
        const modifiedConfig = await injectCustomConfig(baseConfig)
        return modifiedConfig
      },
    },
  },
})

Sample React Vite Apps

React with Webpack

Cypress Component Testing works with React apps that use Webpack 4+ as the bundler.

Webpack Configuration

module.exports = {
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig: require('./webpack.config'),
      // or a function - the result is merged with any
      // webpack.config that is found
      webpackConfig: async () => {
        // ... do things ...
        const modifiedConfig = await injectCustomConfig(baseConfig)
        return modifiedConfig
      },
    },
  },
}

import { defineConfig } from 'cypress'
import webpackConfig from './webpack.config'

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig,
      // or a function - the result is merged with any
      // webpack.config that is found
      webpackConfig: async () => {
        // ... do things ...
        const modifiedConfig = await injectCustomConfig(baseConfig)
        return modifiedConfig
      },
    },
  },
})

If you don't provide a webpack config, Cypress will try to infer it. If Cypress cannot do so, or you want to make modifications to your config, you can specify it via the webpackConfig option.

Sample React Webpack Apps

Community Resources