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 `workspace.json` file.

### Testing Applications

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

You can run your e2e test against a production build with the `--prod` flag

```bash
nx e2e frontend-e2e --prod
```

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 --prod
```

### 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).


Overview

# Cypress Component Testing

> Component testing is in a early preview and 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.

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

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

## 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

Setting Up Cypress

E2E Testing

Creating a Cypress E2E project for an existing project

Testing Applications

Watching for Changes (Headed Mode)

Specifying a Custom Url to Test

Using cypress.config.ts

Package reference

Executors

Generators