Framework Configuration

Writing tests in Cypress is the same regardless of framework choice (Vue, React, Nuxt, Next, etc.). However, each framework requires additional setup and configuration to run properly.

Automatic Setup

Launching Cypress for the first time in a project will start a wizard that will automatically guide you through setup.

To get started, visit the installation guide on how to install and launch Cypress for the first time.

Manual Setup

The rest of this guide covers setting up and 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

Create React App (CRA)

For Create React App, you will need to install the Cypress React Adapter as well as the Cypress Webpack Dev Server as dev dependencies:

npm install --save-dev @cypress/react @cypress/webpack-dev-server

yarn add -D @cypress/react @cypress/webpack-dev-server

Next, you will need to configure component testing.

A dev server is needed to launch component testing. Cypress provides a dev server that works with CRA out of the box. Import 'devServer' from @cypress/react/plugins/react-scripts, then pass in the devServer to the component configuration in the cypress config file.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/react/plugins/react-scripts')

module.exports = defineConfig({
  component: {
    devServer,
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/react/plugins/react-scripts'

export default defineConfig({
  component: {
    devServer,
  },
})

You can find an example Create React App project here.

Next.js

For Next.js, you will need to install the Cypress React Adapter as well as the Cypress Webpack Dev Server as dev dependencies:

npm install --save-dev @cypress/react @cypress/webpack-dev-server

yarn add -D @cypress/react @cypress/webpack-dev-server

A dev server is needed to launch component testing. Cypress provides a dev server that works with Next.js out of the box. Import 'devServer' from @cypress/react/plugins/next, then pass in the devServer to the component configuration in the cypress config file.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/react/plugins/next')

module.exports = defineConfig({
  component: {
    devServer,
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/react/plugins/next'

export default defineConfig({
  component: {
    devServer,
  },
})

You can find an example Next.js project here.

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 in its entirety.

Because of this, we recommend using end-to-end testing over component testing for Next.js pages, and component testing for individual components.

Vite

For React projects that use Vite, you will need to install the Cypress React Adapter as well as the Cypress Vite Dev Server as dev dependencies:

npm install --save-dev @cypress/react @cypress/vite-dev-server

yarn add -D @cypress/react @cypress/vite-dev-server

A dev server is needed to launch component testing. Cypress provides a dev server that works with Vite out of the box. Import 'devServer' from @cypress/vite-dev-server, then pass in the devServer to the component configuration in the cypress config file.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/vite-dev-server')

module.exports = defineConfig({
  component: {
    devServer,
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/vite-dev-server'

export default defineConfig({
  component: {
    devServer,
  },
})

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

Vue 2 & Vue 3

Vue CLI

For Vue CLI projects, you will need to install the Cypress Vue adapter and the Cypress Webpack Dev Server as dev dependencies.

The version of the Cypress Vue adapter you need depends on the version of Vue you are using.

For Vue 3, install the latest @cypress/vue package:

npm install --save-dev @cypress/vue @cypress/webpack-dev-server

yarn add -D @cypress/vue @cypress/webpack-dev-server

For Vue 2, install the @cypress/vue@2 package:

npm install --save-dev @cypress/vue@2 @cypress/webpack-dev-server

yarn add -D @cypress/vue@2 @cypress/webpack-dev-server

A dev server is needed to launch component testing. Import 'devServer' from @cypress/webpack-dev-server, then pass in the devServer to the component configuration in the cypress config file.

You will also need to pass the Webpack config that Vue CLI uses to the dev server. To do so, import the config from @vue/cli-service/webpack.config and pass it into devServerConfig.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/webpack-dev-server')
const webpackConfig = require('@vue/cli-service/webpack.config')

module.exports = defineConfig({
  component: {
    devServer,
    devServerConfig: {
      webpackConfig,
    },
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/webpack-dev-server'
import webpackConfig from '@vue/cli-service/webpack.config'

export default defineConfig({
  component: {
    devServer,
    devServerConfig: {
      webpackConfig,
    },
  },
})

You can find an example Vue 3 CLI project here, and an example Vue 2 CLI project here.

Nuxt

Nuxt uses Vue 2 and Webpack 4 under the hood, so you will need to install the Cypress Webpack Dev Server and Vue 2 adapter, as well as some dev dependencies:

npm install --save-dev cypress @cypress/vue@2 @cypress/webpack-dev-server html-webpack-plugin@4

yarn add -D cypress @cypress/vue@2 @cypress/webpack-dev-server html-webpack-plugin@4

A dev server is needed to launch component testing. Import 'devServer' from @cypress/webpack-dev-server, then pass in the devServer to the component configuration in the cypress config file.

You will also need to pass the Webpack config Nuxt uses to the dev server. To do so, import getWebpackConfig from nuxt and pass it into devServerConfig.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/webpack-dev-server')
const { getWebpackConfig } = require('nuxt')

module.exports = defineConfig({
  component: {
    devServer: async (cypressDevServerConfig) => {
      const webpackConfig = await getWebpackConfig()
      return devServer(cypressDevServerConfig, { webpackConfig })
    },
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/webpack-dev-server'
import { getWebpackConfig } from 'nuxt'

export default defineConfig({
  component: {
    devServer: async (cypressDevServerConfig: Cypress.DevServerConfig) => {
      const webpackConfig = await getWebpackConfig()
      return devServer(cypressDevServerConfig, { webpackConfig })
    },
  },
})

Notice that the call to getWebpackConfig returns a promise. We can load the devServer asynchronously by wrapping the call to devServer in an async function and passing the devServerConfig as the second param into it.

You can find a sample Vue Nuxt project here.

Vite

For Vue projects that use Vite, you will need to install the Cypress Vue Adapter as well as the Cypress Vite Dev Server as dev dependencies:

npm install --save-dev @cypress/vue @cypress/vite-dev-server

A dev server is needed to launch component testing. Cypress provides a dev server that works with Vite out of the box. Import 'devServer' from @cypress/vite-dev-server, then pass in the devServer to the component configuration in the cypress config file.

Copy the following into your cypress config file:

const { defineConfig } = require('cypress')
const { devServer } = require('@cypress/vite-dev-server')

module.exports = defineConfig({
  component: {
    devServer,
  },
})

import { defineConfig } from 'cypress'
import { devServer } from '@cypress/vite-dev-server'

export default defineConfig({
  component: {
    devServer,
  },
})

You can find an example Vue project that uses Vite here.

Component Testing Config

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

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 devServerConfig:

{
  component: {
    devServer,
    devServerConfig: {
      indexHtmlFile: '/custom/path/to/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: {
    devServer,
    specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}'
  }
}

Additional Config

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