Skip to main content

Framework Configuration

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

FrameworkUI LibraryBundler
Create React App 4+React 16+Webpack 4+
Next.js 11+
Alpha
React 16+Webpack 5
React with ViteReact 16+Vite 2
React with WebpackReact 16+Webpack 4+
Vue CLIVue 2+Webpack 4+
Nuxt 2
Alpha
Vue 2+Webpack 4+
Vue with ViteVue 2+Vite 2
Vue with WebpackVue 2+Webpack 4+
info

Currently Cypress does not officially support Component Testing with Angular, but this is planned for a future release. Until then, users may roll their own solution with a custom cy.mount() command, or take as a starting point this unofficial solution from one of our own developers.

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:

  1. Determine what changes need to be merged into your Cypress Config file.
  2. Create a component support file for configuring global styles and installing component libraries.
  3. Globally register the correct cy.mount command based on your framework.
  4. Create component-index.html to let you add your application's fonts and global CDN downloads.
  5. 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',
    },
  },
})

Sample Create React Apps​

Next.js​

caution

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

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​

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

Sample React Vite Apps​

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')
const webpackConfig = require('./webpack.config')

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

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

caution

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

Nuxt Sample Apps​

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

Vue Vite Sample Apps​

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')
const webpackConfig = require('./webpack.config')

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

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: () => {},
      }
    },
  },
})

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:

const { defineConfig } = require('cypress')

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

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  component: {
    specPattern: 'src/**/*.cy.{js,jsx,ts,tsx}',
  },
})

Additional Config​

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