The Nx Plugin for Cypress contains executors and generators allowing your workspace to use the powerful Cypress integration testing capabilities.

![Cypress logo](/shared/cypress-logo.png)

Cypress is a test runner built for the modern web. It has a lot of great features:

- Time travel
- Real-time reloads
- Automatic waiting
- Spies, stubs, and clocks
- Network traffic control
- Screenshots and videos

## Setting Up Cypress

> Info about [Cypress Component Testing can be found here](/cypress/cypress-component-testing)

If the `@nrwl/cypress` package is not installed, install the version that matches your `nx` package version.

```bash
yarn add --dev @nrwl/cypress
```

```bash
npm install --save-dev @nrwl/cypress
```

## E2E Testing

By default, when creating a new frontend application, Nx will use Cypress to create the e2e tests project.

```bash
nx g @nrwl/web:app frontend
```

### Creating a Cypress E2E project for an existing project

To generate an E2E project based on an existing project, run the following generator

```bash
nx g @nrwl/cypress:cypress-project your-app-name-e2e --project=your-app-name
```

Optionally, you can use the `--baseUrl` option if you don't want cypress plugin to serve `your-app-name`.

```bash
nx g @nrwl/cypress:cypress-project your-app-name-e2e --baseUrl=http://localhost:4200
```

Replace `your-app-name` with the app's name as defined in your `tsconfig.base.json` file or the `name` property of your `package.json`.

### Testing Applications

Run `nx e2e frontend-e2e` to execute e2e tests with Cypress.

You can run your e2e test against a production build by using the `production` [configuration](https://nx.dev/recipe/use-executor-configurations#use-executor-configurations)

```bash
nx e2e frontend-e2e --configuration=production
```

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 in `dist/cypress/apps/frontend/screenshots` and `dist/cypress/apps/frontend/videos`.

### Watching for Changes (Headed Mode)

With, `nx e2e frontend-e2e --watch` Cypress will start in headed mode where you can see your application being tested.

Running Cypress with `--watch` is a great way to enhance dev workflow - you can build up test files with the application
running and Cypress will re-run those tests as you enhance and add to the suite.

```bash
nx e2e frontend-e2e --watch
```

### Specifying a Custom Url to Test

The `baseUrl` property provides you the ability to test an application hosted on a specific domain.

```bash
nx e2e frontend-e2e --baseUrl=https://frontend.com
```

> If no `baseUrl` and no `devServerTarget` are provided, Cypress will expect to have the `baseUrl` property in
> the cypress config file, or will error.

## Using cypress.config.ts

If you need to fine tune your Cypress setup, you can do so by modifying `cypress.config.ts` in the project root. For
instance,
you can easily add your `projectId` to save all the screenshots and videos into your Cypress dashboard. The complete
configuration is documented
on [the official website](https://docs.cypress.io/guides/references/configuration.html#Options).

## Environment Variables

If you're needing to pass a variable to cypress that you wish to not commit to your repository, i.e. API keys, or dynamic values based on configurations, i.e. API Urls. This is where [Cypress environment variables](https://docs.cypress.io/guides/guides/environment-variables) can be used.

There are a handful of ways to pass environment variables to Cypress, but the most common is going to be via the [`cypress.env.json` file](https://docs.cypress.io/guides/guides/environment-variables#Option-1-configuration-file), the [env executor option for cypress](https://nx.dev/packages/cypress/executors/cypress#env) or the commandline.

Create a `cypress.env.json` file in the projects root i.e. `apps/my-cool-app-e2e/cypress.env.json`. Cypress will automatically pick up this file. This method is helpful for configurations that you want to not commit. Just don't forget to add the file to the `.gitignore` and add documentation so people in your repo know what values to popluate in their local copy of the `cypress.env.json` file.

Using [@nrwl/cypress:cypress](/packages/cypress/executors/cypress) env executor option is a good way to add values you want to define that you don't mine commit to the repository, such as a base API url. You can leverage [target configurations](/reference/project-configuration#targets) to define different values as well.

Optionally, you can pass environment variables via the commandline with the `--env` flag.

{% callout type="warning" title="Executor options and --env" %}
When using the `--env` flag, this will not be merged with any values used in the `env` executor option.
{% /callout %}

```bash
nx e2e frontend-e2e --env.API_URL="https://api.my-nx-website.com" --env.API_KEY="abc-123"
```


Overview

# Cypress Component Testing

> Component testing requires Cypress v10 and above.
> See our [guide for more information](/cypress/v10-migration-guide) to migrate to Cypress v10.

Unlike [E2E testing](/packages/cypress), component testing does not create a new project. Instead, Cypress component testing is added
directly to a project, like [Jest](/packages/jest)

## Add Component Testing to a Project

> Currently only [@nrwl/react](/packages/react/generators/cypress-component-configuration) and [@nrwl/angular](/packages/angular/generators/cypress-component-configuration) plugins support component testing

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

```bash
nx g @nrwl/react:cypress-component-configuration --project=your-project

nx g @nrwl/angular: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 leverages a build target within your workspace as the base for running the tests. The build target is usually an app within the workspace. By default, the generator attempts to find the build target for you based on the project usage, but you can manually specify the build target to use via the `--build-target` option.

```bash
nx g @nrwl/react:cypress-component-configuration --project=your-project --build-target=my-react-app:build

nx g @nrwl/angular:cypress-component-configuration --project=your-project --build-target=my-ng-app:build
```

The build target option can be changed later via updating the `devServerTarget` option in the `component-test` target.

{% callout type="warning" title="Executor Options" %}
When using component testing make sure to set `skipServe: true` in the component test target options, otherwise `@nrwl/cypress` will attempt to run the build first which can slow down your component tests. `skipServe: true` is automatically set when using the `cypress-component-configuration` generator.
{% /callout %}

## Testing Projects

Run `nx 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 in `dist/cypress/libs/your-lib/screenshots` and `dist/cypress/libs/your-lib/videos`.

## Watching for Changes (Headed Mode)

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.

## More Information

You can read more on component testing in the [Cypress documentation](https://docs.cypress.io/guides/component-testing/writing-your-first-component-test).


Component Testing

# Migrating to Cypress V10

Cypress v10 introduce new features, like component testing, along with some breaking changes.

Before continuing, make sure you have all your changes committed and have a clean working tree.

You can migrate an E2E project to v10 by running the following command:

```bash
nx g @nrwl/cypress:migrate-to-cypress-10
```

In general, these are the steps taken to migrate your project:

1. Migrates your existing `cypress.json` configuration to a new `cypress.config.ts` configuration file.
   - The `pluginsFile` option has been replaced for `setupNodeEvents`. We will import the file and add it to
     the `setupNodeEvents` config option. Double-check your plugins are working correctly.
2. Rename all test files from `.spec.ts` to `.cy.ts`
3. Rename the `support/index.ts` to `support/e2e.ts` and update any associated imports
4. Rename the `integrations` folder to the `e2e` folder

We take the best effort to make this migration seamless, but there can be edge cases we didn't anticipate. So feel free to [open an issue](https://github.com/nrwl/nx/issues/new?assignees=&labels=type%3A+bug&template=1-bug.md) if you come across any problems.

You can also consult the [official Cypress migration guide](https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0) if you get stuck and want to manually migrate your projects.


v10 Migration Guide

cypress

The address (with the port) which your application is running on.

A unique identifier for a run to enable grouping or parallelization.

A regex string that is used to choose what additional integration files to copy to the dist folder.

The path of the Cypress configuration json file.

A key-value Pair of environment variables to pass to Cypress runner.

Whether or not the Cypress Test Runner will stay open after running tests in a spec file.

A named group for recorded runs in the Cypress dashboard.

Displays the browser instead of running headlessly. Set this to `true` if your run depends on a Chrome extension being loaded.

Hide the browser instead of running headed (default for cypress run).

A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. Cypress uses minimatch with the options: `{dot: true, matchBase: true}`. We suggest using https://globster.xyz to test what files would match.

The key cypress should use to run tests in parallel/record the run (CI only).

Whether or not Cypress should run its tests in parallel (CI only).

Whether or not Cypress should record the results of the tests.

The reporter options used. Supported options depend on the reporter.

A comma delimited glob string that is provided to the Cypress runner to specify which spec files to run. i.e. `**examples/**,**actions.spec**`.

The path of the Cypress tsconfig configuration json file.

Recompile and run tests when files change.

Cypress Target

init

Add Cypress Configuration to the workspace.

Do not add dependencies to `package.json`.

Add Cypress Configuration to the workspace

cypress-project

Create Cypress Configuration for the workspace.

Generate JavaScript files rather than TypeScript files.

The name of the frontend project to test.

Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.

Split the project configuration into `<projectRoot>/project.json` rather than including it inside workspace.json.

Create Cypress Configuration for the workspace

Set up Cypress Component Test for a project

cypress-component-project

Set up Cypress component test for a project.

Add cypress component testing to an existing project named my-cool-lib

The name of the project to add cypress component testing to

Set up Cypress component testing for a project

Migrate existing Cypress e2e projects to Cypress v10

migrate-to-cypress-10

Migrate Cypress e2e project from v8/v9 to Cypress v10.

Migrate existing cypress projects to Cypress v10

@nrwl/cypress:cypress

Options playground

Options

baseUrl

browser

cypressConfig

copyFiles

ciBuildId

devServerTarget

exit

env

group

headed

headless

ignoreTestFiles

key

parallel

record

reporter

reporterOptions

spec

skipServe

tsConfig

testingType

tag

watch

Additional Properties