Framework Configuration

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 for component testing:

Automatic Setup

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.

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 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',
    },
  },
})

You can find an example Create React App project here.

Next.js

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',
    },
  },
})

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 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.

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',
    },
  },
})

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

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:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  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.

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',
    },
  },
})

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

Nuxt

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',
    },
  },
})

You can find a sample Vue Nuxt project here.

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',
    },
  },
})

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

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:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  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.

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

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 configuration reference.