Framework Configuration

Cypress Component Testing is currently in beta.

Writing tests in Cypress is the same regardless of whichever UI library you choose (React or Vue, currently). However, each framework requires a different setup configuration.

Cypress currently supports the following frameworks and versions for component testing:

Framework	UI Library	Bundler
Create React App 4+	React 16+	Webpack 4+
Next.js 11+ Alpha	React 16+	Webpack 5
React with Vite	React 16+	Vite 2
React with Webpack	React 16+	Webpack 4+
Vue CLI	Vue 2+	Webpack 4+
Nuxt 2 Alpha	Vue 2+	Webpack 4+
Vue with Vite	Vue 2+	Vite 2
Vue with Webpack	Vue 2+	Webpack 4+

Automatic Configuration (Recommended)

When you launch Cypress for the first time in a project and select Component Testing, the app will automatically guide you and set up your configuration.

Cypress offers automatic configuration for supported front-end frameworks and bundlers.

For first-time setup of React or Vue apps, we strongly recommend using automatic configuration to create all of the necessary configuration files.

Automatic Configuration Setup

You should use the Cypress Launchpad to configure Component Testing for the first time. To start the setup wizard, simply open Cypress and choose "Component Testing".

cypress open

The Launchpad's setup wizard will do the following things:

Determine what changes need to be merged into your Cypress Config file.
Create a component support file for configuring global styles and installing component libraries.
Globally register the correct cy.mount command based on your framework.
Create component-index.html to let you add your application's fonts and global CDN downloads.
Add any framework-specific setup to your support files.

Once you click through all of the prompts, you'll be asked to choose a browser and launch the Cypress App.

Manual Setup

The rest of this guide covers configuring your project manually.

Prerequisites

Install Cypress.
Create an empty cypress.config.js (or .ts) file at the root of your project.
Create an empty cypress/support/component.js (or .ts) file.

Next, follow the instructions for your framework.

React

For React apps, we have built-in support for Create React App, Next.js, Vite, and a custom webpack config.

Create React App (CRA)

To configure component testing for a React app that uses Create React App, you will need to configure a devServer with a framework of "create-react-app" and a bundler of "webpack" like so:

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

Next.js is currently in alpha support for component testing. See Next.js Caveats for more info on current limitations.

To configure component testing for a React app that uses Next.js, you will need to configure a devServer with a framework of "next" and a bundler of "webpack" like so:

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 end-to-end 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 12 with TypeScript

React with Vite

To configure component testing for a React app that uses Vite, you will need to configure a devServer with a framework of "react" and a bundler of "vite" like so:

const { defineConfig } = require('cypress')

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

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
    },
  },
})

Sample React Vite Apps

React Vite with TypeScript

React with Webpack

To configure component testing for a React app that uses a custom Webpack config, you will need to configure a devServer with a framework of "react" and a bundler of "webpack" like so:

module.exports = {
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig: require('./webpack.config'),
    },
  },
})

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

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig,
    },
  },
})

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

You can find an example React project that uses Webpack here.

Vue 2 & Vue 3

For Vue apps, we have built-in support for Vue CLI, Nuxt, Vite, and a custom webpack config.

Vue CLI

To configure component testing for a Vue app that uses Vue CLI, you will need to configure a devServer with a framework of "vue-cli" and a bundler of "webpack" like so:

const { defineConfig } = require('cypress')

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

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'vue-cli',
      bundler: 'webpack',
    },
  },
})

PWA Caveat

If you use the Vue CLI's PWA feature, there is a known caveat regarding configuration. See here for more information.

Sample Vue CLI Apps

Nuxt

Nuxt is currently in alpha support for component testing.

To configure component testing for a Vue app that uses Nuxt, you will need to configure a devServer with a framework of "nuxt" and a bundler of "webpack" like so:

const { defineConfig } = require('cypress')

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

import { defineConfig } from 'cypress'

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

Nuxt Sample Apps

Vue 2 Nuxt 2 with JavaScript

Vue with Vite

To configure component testing for a Vue app that uses Vite, you will need to configure a devServer with a framework of "vue" and a bundler of "vite" like so:

const { defineConfig } = require('cypress')

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

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'vue',
      bundler: 'vite',
    },
  },
})

Vue Vite Sample Apps

Vue 3 Vite with TypeScript

Vue with Webpack

To configure component testing for a Vue app that uses a custom Webpack config, you will need to configure a devServer with a framework of "vue" and a bundler of "webpack" like so:

module.exports = {
  component: {
    devServer: {
      framework: 'vue',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig: require('./webpack.config'),
    },
  },
}

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

export default defineConfig({
  component: {
    devServer: {
      framework: 'vue',
      bundler: 'webpack',
      // optionally pass in webpack config
      webpackConfig,
    },
  },
})

If you don't provide one, Cypress will try to infer your webpack config. If Cypress cannot or you want to make modifications to your config, you can pass it in manually via the webpackConfig option.

Vue Webpack Sample Apps

Vue 3 Webpack 5 with TypeScript

Component Testing Config

Below are a few additional configuration values that are specific to component testing.

Custom Dev Server

A custom function can be passed into the devServer option, which allows the use of other dev servers not provided by Cypress out of the box. These can be from the Cypress community, preview builds not included with the app, or a custom one you create.

The function's signature takes in a Cypress Configuration object as its only parameter and returns either an instance of a devServer or a promise that resolves to a devServer instance.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    devServer(cypressConfig) {
      // return devServer instance or a promise that resolves to
      // a dev server here
      return {
        port: 1234,
        close: () => {},
      }
    },
  },
})

import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer(cypressConfig: CypressConfiguration) {
      // return devServer instance or a promise that resolves to
      // a dev server here
      return {
        port: 1234,
        close: () => {},
      }
    },
  },
})

Custom Index File

By default, Cypress renders your components into an HTML file located at cypress/support/component-index.html.

The index file allows you to add in global assets, such as styles, fonts, and external scripts.

You can provide an alternative path to the file using the indexHtmlFile option in the component config options:

{
  component: {
    devServer,
    indexHtmlFile: '/custom/path/to/component-index.html'
  }
}

Spec Pattern for Component Tests

By default, Cypress looks for spec files anywhere in your project with an extension of .cy.js, .cy.jsx, .cy.ts, or .cy.tsx. However, you can change this behavior for component tests with a custom specPattern value. In the following example, we've configured Cypress to look for spec files with those same extensions, but only in the src folder or any of its subdirectories.

{
  component: {
    specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}'
  }
}

Additional Config

For more information on all the available configuration options, see the configuration reference.