@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 v11 via the migrate-to-cypress-11 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. However, this functionality is deprecated, and will be removed on Nx version 19.
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
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});
9The 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});
9Here 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});
12The 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
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
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
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}
14Nx also supports Angular component testing.
Usage
1nx generate cypress-component-configuration ...
2By 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 ...
2Show what will be generated without writing to disk:
1nx g cypress-component-configuration ... --dry-run
2Examples
Add component testing to your react project:
1nx g @nx/react:cypress-component-configuration --project=my-react-project
2Add 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
2Options
project
Required
string
The name of the project to add cypress component testing configuration to
generateTests
boolean
Default:
falseGenerate 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
InternalHidden
string
Accepted values:
vite, webpackThe bundler to use for Cypress Component Testing.
skipFormat
Internal
boolean
Default:
falseSkip formatting files