@nx/cypress - Generators

The @nx/cypress plugin provides various generators to help you create and configure cypress projects within your Nx workspace. Below is a complete reference for all available generators and their options.

`configuration`

Add a Cypress configuration to an existing project.

This is a generator to add a cypress e2e configuration to an existing project.

nx g @nx/cypress:configuration --project=my-cool-project --devServerTarget=some-app:serve

Running this generator, adds the required files to run cypress tests for a project, Mainly a cypress.config.ts file and default files in the <project-root>/cypress/ directory. Tests will be located in <project-root>/cypress/e2e/* by default.

You can customize the directory used via the --directory flag, the value is relative to the project root.

For example if you wanted to place the files inside an e2e folder

nx g @nx/cypress:configuration --project=my-cool-project --devServerTarget=some-app:serve --directory=e2e

Providing a --devServerTarget is optional if you provide a --baseUrl or the project you’re adding the configuration to has a serve target already. Otherwise, a --devServerTarget is recommend for the @nx/cypress:cypress executor to spin up the dev server for you automatically when needed.

Feature Based Testing

This generator helps in creating feature based e2e/integration testing setups where you can place the feature tests in the same project as the feature library. This differs from creating a separate e2e project that contained all tests for an application which can easily cause more tests to run than is strictly necessary.

Take the following workspace where the feature-cart project is affected.

{% graph height=“450px” %}

{
  "projects": [
    {
      "type": "app",
      "name": "fancy-app",
      "data": {
        "tags": []
      }
    },
    {
      "type": "app",
      "name": "fancy-app-e2e",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "feature-user",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "feature-dashboard",
      "data": {
        "tags": []
      }
    },
    {
      "type": "lib",
      "name": "feature-cart",
      "data": {
        "tags": []
      }
    }
  ],
  "groupByFolder": false,
  "workspaceLayout": {
    "appsDir": "apps",
    "libsDir": "libs"
  },
  "dependencies": {
    "fancy-app": [
      {
        "target": "feature-user",
        "source": "fancy-app",
        "type": "static"
      },
      {
        "target": "feature-cart",
        "source": "fancy-app",
        "type": "static"
      }
    ],
    "fancy-app-e2e": [
      {
        "target": "fancy-app",
        "source": "fancy-app-e2e",
        "type": "implicit"
      }
    ],
    "feature-user": [
      {
        "target": "feature-dashboard",
        "source": "feature-user",
        "type": "direct"
      }
    ],
    "feature-cart": [],
    "feature-dashboard": []
  },
  "affectedProjectIds": ["feature-cart", "fancy-app", "fancy-app-e2e"]
}

{% /graph %}

In this case, if tests for the all the feature-* projects where contained in the fancy-app-e2e project, then all of those features will be tested in the app, when only the feature-cart tests need to run.

Running these e2e/integration tests more often than they should results in longer CI times.

Brining those e2e test closer to each feature can result is lowering CI times since we don’t need to test those features if they did not change.

Building this way leaves the fancy-app-e2e for mostly smoke type testing instead of more in-depth feature testing.

Using the @nx/cypress:configuration generator can help you accomplish this in your workspace.

nx g @nx/cypress:configuration --project=feature-cart --devServerTarget=fancy-app:serve
nx g @nx/cypress:configuration --project=feature-user --devServerTarget=fancy-app:serve
nx g @nx/cypress:configuration --project=feature-dashboard --devServerTarget=fancy-app:serve

Each project will now get their own e2e target, where the feature project is only concerned with itself. This allows for more focused tests without worrying about forcing unrelated tests to also run.

It’s important to remember that these feature tests are still going to be leveraging the same app to run the tests against so if you plan to run in parallel, you can leverage using a file server and the ability for @nx/cypress:cypress executor to pass through a port or find a free port to allow running tests in parallel. Read more about the —port flag

Usage:

nx generate @nx/cypress:configuration [options]

Aliases: cypress-e2e-configuration, e2e, e2e-config

Options

Option	Type	Description	Default
`project`	string [required]	The project to add a Cypress configuration to
`baseUrl`	string	The address (with the port) which your application is running on. If you wish to start your application when running the e2e target, then use —devServerTarget instead.
`bundler`	string	The Cypress bundler to use.	`"webpack"`
`devServerTarget`	string	A devServerTarget,’:[:], that will be used to run tests against. This is usually the app this project will be used in. Pass —baseUrl if you wish to not use a devServerTarget.
`directory`	string	A directory where the project is placed relative from the project root	`"cypress"`
`js`	boolean	Generate JavaScript files rather than TypeScript files.	`false`
`jsx`	boolean	Whether or not this project uses JSX.	`true`
`linter`	string	The tool to use for running lint checks.
`port`	string	Set the ‘port’ option on the e2e target. It’s recommend to set a different port so you can run tests e2e targets in parallel. Most dev servers support using ‘0’ to automatically find a free port. The value ‘cypress-auto’ can be used if the underlying dev server does not support automatically finding a free port.
`rootProject`	boolean	Create a application at the root of the workspace	`false`
`setParserOptionsProject`	boolean	Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.	`false`
`skipFormat`	boolean	Skip formatting files.	`false`
`skipPackageJson`	boolean	Do not add dependencies to `package.json`.	`false`

`convert-to-inferred`

Convert existing Cypress project(s) using @nx/cypress:cypress executor to use @nx/cypress/plugin.

Usage:

nx generate @nx/cypress:convert-to-inferred [options]

Options

Option	Type	Description	Default
`project`	string	The project to convert from using the `@nx/cypress:cypress` executor to use `@nx/cypress/plugin`.
`skipFormat`	boolean	Whether to format files at the end of the migration.	`false`

`migrate-to-cypress-11`

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

Usage:

nx generate @nx/cypress:migrate-to-cypress-11 [options]

 ## Getting Help

 You can get help for any generator by adding the `--help` flag:

 ```bash
 nx generate @nx/cypress:<generator> --help
 ```