React Component Testing

What you'll learn ​

• How to set up component tests in React
• How to use Cypress with different React frameworks and bundlers

Framework Support ​

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

• Create React App
• Next.js
• React with Vite
• React with Webpack

Tutorial ​

Visit the Getting Started Guide for a step-by-step tutorial on adding component testing to any project and how to write your first tests.

Installation ​

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

• npm
• yarn
• pnpm
npm install cypress --save-dev

Open Cypress:

• npm
• yarn
• pnpm
npx cypress open


Choose Component Testing

The Cypress Launchpad will guide you through configuring your project.

info

For a step-by-step guide on how to create a component test, refer to the Getting Started guide.

For usage and examples, visit the React Examples guide.

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 ​

• cypress.config.js
• cypress.config.ts
const { defineConfig } = require('cypress')

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

Sample Create React Apps ​

• CRA 4 with JavaScript
• CRA 5 with TypeScript

Next.js ​

Cypress Component Testing works with Next.js 11+.

Next.js Configuration ​

• cypress.config.js
• cypress.config.ts
const { defineConfig } = require('cypress')

module.exports = 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 ​

• Next.js 13 with TypeScript

React with Vite ​

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

Vite Configuration ​

• cypress.config.js
• cypress.config.ts
const { defineConfig } = require('cypress')
const customViteConfig = require('./customConfig')

module.exports = 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 Vite with TypeScript

React with Webpack ​

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

Webpack Configuration ​

• cypress.config.js
• cypress.config.ts
const { defineConfig } = require('cypress')
const webpackConfig = require('./webpack.config')

module.exports = 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 ​

• React Webpack 5 with JavaScript

Community Resources ​