@nx/react:cypress-component-configuration

Add a Cypress component testing configuration to an existing project.

Can I use component testing?

React component testing with Nx requires Cypress version 10.7.0 and up.

You can migrate with to v10 via the migrate-to-cypress-10 generator.

This generator is for Cypress based component testing.

If you want to test components via Storybook with Cypress, then check out the storybook-configuration generator docs

This generator is designed to get your React project up and running with Cypress Component Testing.

nx g @nx/react:cypress-component-configuration --project=my-cool-react-project

Nx 15 and lower use @nrwl/ instead of @nx/

Running this generator, adds the required files to the specified project with a preconfigured cypress.config.ts designed for Nx workspaces.

The following file will be added to projects where the Component Testing build target is using webpack for bundling:

cypress.config.ts
1import { defineConfig } from 'cypress'; 2import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing'; 3 4export default defineConfig({ 5 component: nxComponentTestingPreset(__filename, { 6 bundler: 'webpack', 7 }), 8}); 9
Nx 15 and lower use @nrwl/ instead of @nx/

The following file will be added to projects where the Component Testing build target is using vite for bundling:

cypress.config.ts
1import { defineConfig } from 'cypress'; 2import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing'; 3 4export default defineConfig({ 5 component: nxComponentTestingPreset(__filename, { 6 bundler: 'vite', 7 }), 8}); 9
Nx 15 and lower use @nrwl/ instead of @nx/

Here is an example on how to add custom options to the configuration

cypress.config.ts
1import { defineConfig } from 'cypress'; 2import { nxComponentTestingPreset } from '@nx/react/plugins/component-testing'; 3 4export default defineConfig({ 5 component: { 6 ...nxComponentTestingPreset(__filename, { 7 bundler: 'webpack', 8 }), 9 // extra options here 10 }, 11}); 12
Nx 15 and lower use @nrwl/ instead of @nx/

The bundler option

Component testing supports two different bundlers: webpack and vite. The Nx generator will pick up the bundler used in the specified project's build target. If the build target is using @nx/webpack:webpack, then the generator will use webpack as the bundler. If the build target is using @nx/vite:build, then the generator will use vite as the bundler.

You can manually set the bundler by passing --bundler=webpack or --bundler=vite to the generator, but that is not needed since the generator will pick up the correct bundler for you. However, if you want to use a different bundler than the one that is used in the build target, then you can manually set it using that flag.

Specifying a Build Target

Component testing requires a build target to correctly run the component test dev server. This option can be manually specified with --build-target=some-react-app:build, but Nx will infer this usage from the project graph if one isn't provided.

For React projects, the build target needs to be using the @nx/webpack:webpack executor. The generator will throw an error if a build target can't be found and suggest passing one in manually.

Letting Nx infer the build target by default

nx g @nx/react:cypress-component-configuration --project=my-cool-react-project

Nx 15 and lower use @nrwl/ instead of @nx/

Manually specifying the build target

nx g @nx/react:cypress-component-configuration --project=my-cool-react-project --build-target:some-react-app:build --generate-tests

Nx 15 and lower use @nrwl/ instead of @nx/
Build Target with Configuration

If you're wanting to use a build target with a specific configuration. i.e. my-app:build:production, then manually providing --build-target=my-app:build:production is the best way to do that.

Auto Generating Tests

You can optionally use the --generate-tests flag to generate a test file for each component in your project.

nx g @nx/react:cypress-component-configuration --project=my-cool-react-project --generate-tests

Nx 15 and lower use @nrwl/ instead of @nx/

Running Component Tests

A new component-test target will be added to the specified project to run your component tests.

nx g component-test my-cool-react-project

Here is an example of the project configuration that is generated. The --build-target option is added as the devServerTarget which can be changed as needed.

project.json
1{ 2 "targets" { 3 "component-test": { 4 "executor": "@nx/cypress:cypress", 5 "options": { 6 "cypressConfig": "<path-to-project-root>/cypress.config.ts", 7 "testingType": "component", 8 "devServerTarget": "some-react-app:build", 9 "skipServe": true 10 } 11 } 12 } 13} 14
Nx 15 and lower use @nrwl/ instead of @nx/

Nx also supports Angular component testing.

Usage

1nx generate cypress-component-configuration ... 2

By default, Nx will search for cypress-component-configuration in the default collection provisioned in workspace.json.

You can specify the collection explicitly as follows:

1nx g @nx/react:cypress-component-configuration ... 2
Nx 15 and lower use @nrwl/ instead of @nx/

Show what will be generated without writing to disk:

1nx g cypress-component-configuration ... --dry-run 2

Examples

Add component testing to your react project:

1nx g @nx/react:cypress-component-configuration --project=my-react-project 2
Nx 15 and lower use @nrwl/ instead of @nx/

Add component testing to your react project and generate component tests for your existing components:

1nx g @nx/react:cypress-component-configuration --project=my-react-project --generate-tests 2
Nx 15 and lower use @nrwl/ instead of @nx/

Options

project

Required
string

The name of the project to add cypress component testing configuration to

generateTests

boolean
Default: false

Generate default component tests for existing components in the project

buildTarget

string
Pattern: ^[^:\\s]+:[^:\\s]+(:\\S+)?$

A build target used to configure Cypress component testing in the format of project:target[:configuration]. The build target should be from a React app. If not provided we will try to infer it from your projects usage.

bundler

Hidden
string
Accepted values: vite, webpack

The bundler to use for Cypress Component Testing.

skipFormat

boolean
Default: false

Skip formatting files