@nx/cypress:cypress

Run Cypress for e2e, integration and component testing.

Options can be configured in project.json when defining the executor, or when invoking it. Read more about how to configure targets and executors here: https://nx.dev/reference/project-configuration#targets.

Depending on your testing type, the Cypress executor is configured in different ways. The following are sample configurations that are created via the cypress-project and cypress-component-project generators.

"targets": {
  "e2e": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/app-e2e/cypres.config.ts",
      "devServerTarget": "my-react-app:serve",
      "testingType": "e2e"
    }
  }
}
Nx 15 and lower use @nrwl/ instead of @nx/

API Testing

API testing with Cypress is the same setup as e2e testing. Just change which devServerTarget is used!

Providing a Base URL

If devServerTarget is provided, the url returned from started the dev server will be passed to cypress as the baseUrl option.

Defining a baseUrl in the executor options will override the inferred baseUrl from the devServerTarget.

The baseUrl defined in the Cypress config file is the last value used if no url is found in the devServerTarget or executor options.

Static Serving

When running in CI it doesn't make sense to start up a dev server since there aren't changes to watch for.

You can use @nx/web:file-server to serve the pre-built static files of your frontend project.

In some frontend application, add a 'static-serve' target.

"serve-static": {
  "executor": "@nx/web:file-server",
  "options":{
    "buildTarget": "frontend:build"
  }
}
Nx 15 and lower use @nrwl/ instead of @nx/

In the e2e application add a configuration to change devServerTarget to point to the static-serve from the frontend application

"e2e": {
  //...
  "configurations": {
    "ci": {
      "devServerTarget": "frontend:serve-static"
    }
  }
}

What about Node projects?

The same can be done for backend node apps with @nx/js:node executor

nx e2e my-app-e2e --configuration=ci

Environment Variables

Using executor configurations offers flexibility to set environment variables

"targets": {
  "e2e": {
    "executor": "@nx/cypress:cypress",
    "options": {
      "cypressConfig": "apps/app-e2e/cypres.config.ts",
      "devServerTarget": "my-react-app:serve",
      "testingType": "e2e"
    },
    "configurations": {
      "qa": {
        "env": {
          "API_URL": "https://api.qa.company.com"
        }
      },
      "dev": {
        "env": {
          "API_URL": "http://locahost:3333/api"
        }
      }
    }
  }
}
Nx 15 and lower use @nrwl/ instead of @nx/

Read more on different ways to use environment variables for cypress executor

Options playground

Try out this interactive editor of the configuration object. Values are validated as you type and hovering over labels will give you more information.

Examples

These buttons show the config object for specific common tasks.

Options

cypressConfig

Required

string

The path of the Cypress configuration json file.

baseUrl

string

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

browser

string

The browser to run tests in.

ciBuildId

oneOf [string, number]

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

devServerTarget

string

Dev server target to run tests against.

exit

boolean

Default: true

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

env

object: object

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

group

string

A named group for recorded runs in the Cypress dashboard.

headed

boolean

Default: false

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

ignoreTestFiles

string

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.

key

string

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

parallel

boolean

Default: false

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

port

oneOf [string, number]

Pass a specified port value to the devServerTarget, if the value is 'cypress-auto' a free port will automatically be picked for the devServerTarget.

record

boolean

Default: false

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

reporter

string

The reporter used during cypress run.

reporterOptions

string

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

spec

string

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

skipServe

boolean

Default: false

Skip dev-server build.

tsConfig

string

The path of the Cypress tsconfig configuration json file.

testingType

string

Default: e2e

Accepted values: component, e2e

Specify the type of tests to execute.

tag

string

A comma delimited list to identify a run with.

watch

boolean

Default: false

Recompile and run tests when files change.

Additional Properties

anything

Extra properties of any type may be provided to this object.

copyFiles

Deprecated

string

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

No longer used since cypress supports typescript out of the box. If specified, it will be ignored.

headless

Deprecated

boolean

Default: false

Hide the browser instead of running headed.

Cypress runs headless by default. Use the --watch flag to control head/headless behavior instead.