Component testing requires Cypress v10 and above. See ourguide for more information to migrate to Cypress v10.

UnlikeE2E testing, component testing does not create a new project. Instead, Cypress component testing is added directly to a project, likeJest

Currently only@nx/react,@nx/angular, and@nx/next plugins support component testing

Use thecypress-component-configuration generator from the respective plugin to add component testing to a project.

nxg@nx/react:cypress-component-configuration--project=your-project
nxg@nx/angular:cypress-component-configuration--project=your-project
nxg@nx/next:cypress-component-configuration--project=your-project

You can optionally pass in--generate-tests to create component tests for all components within the library.

Component testing supports both applications and libraries. By default, the generator attempts to find the build target for you based on the project's dependent apps. But you can manually specify the build target to use via the--build-target option. Note, in most cases, the build target will be from a different project than the one being configured. The only case where the build targets are from the same project is when the component tests are being added to an application.

Note: The@nx/next:cypress-component-configuration generator doesn't require a build target

nxg@nx/react:cypress-component-configuration--project=your-project--build-target=my-react-app:build
nxg@nx/angular:cypress-component-configuration--project=your-project--build-target=my-ng-app:build

The build target option can be changed later via updating thedevServerTarget option in thecomponent-test target.

When using thecypress-component-configuration generator, a helper function is used in thecypress.config.ts to setup the ideal settings for your project.

If you need to add additional configuration properties, you can spread the returned object from the helper function.

exportdefaultdefineConfig({
component: {
...nxComponentTestingPreset(__filename),
// add your own config here
},
});

Runnx component-test your-lib to execute the component tests with Cypress.

By default, Cypress will run in headless mode. You will have the result of all the tests and errors (if any) in your terminal. Screenshots and videos will be accessible indist/cypress/libs/your-lib/screenshots anddist/cypress/libs/your-lib/videos.

With,nx component-test your-lib --watch Cypress will start in headed mode. Where you can see your component being tested.

Running Cypress with--watch is a great way to iterate on your components since cypress will rerun your tests as you make those changes validating the new behavior.

Nx provides powerful features fordistributing tasks in CI, includingsplitting tasks by file (also known as atomization). The@nx/cypress plugin facilitates this for Cypress projects, allowing you to run your tests more efficiently in your Continuous Integration (CI) environment.

To enable component testing task splitting, set theciComponentTestingTargetName option of the@nx/cypress/plugin in yournx.json file. It will look something like this:

{
"plugins": [
{
"plugin":"@nx/cypress/plugin",
"options": {
"targetName":"e2e",
"ciTargetName":"e2e-ci",
"componentTestingTargetName":"component-test",
"ciComponentTestingTargetName":"component-test-ci",
"openTargetName":"open-cypress"
}
}
]
}

The plugin will infer thecomponent-test-ci task, which depends on individual component testing tasks for each file. You can then replace thecomponent-test task with thecomponent-test-ci task in your CI configuration to run your tests in a distributed fashion:

-run:pnpm exec nx affected -t lint test build component-test
-run:pnpm exec nx affected -t lint test build component-test-ci

You can read more on component testing in theCypress documentation.