Skip to main content
Cypress App

React Component Testing

info
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 18 and 19 with the following frameworks:

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 install cypress --save-dev

Open Cypress:

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 Vite, Next.js, 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.

React with Vite​

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

Vite Configuration​

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 with Webpack​

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

Webpack Configuration​

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​

Next.js​

Cypress Component Testing works with Next.js 14 and Next.js 15.

Next.js Configuration​

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​

Community Resources​

Contents