Command Line

This guide assumes you've already read our Installing Cypress guide and installed Cypress as an npm module. After installing you'll be able to execute all of the commands in this document from your project root.

How to run commands

You can run Cypress from your project root using a command which depends on the package manager you are using: npm, Yarn or pnpm. For example, you would prefix the command cypress run as shown:

npm

npx cypress run

yarn

yarn cypress run

pnpm

pnpm cypress run

Add any required options to the end of the command line. As an example, if you want to run tests in headless mode from a single spec file and record the results with Cypress Cloud, the command should be:

npm

npx cypress run --record --spec "cypress/e2e/my-spec.cy.js"

Yarn

yarn cypress run --record --spec "cypress/e2e/my-spec.cy.js"

pnpm

pnpm cypress run --record --spec "cypress/e2e/my-spec.cy.js"

info

You can alternatively require and run Cypress as a node module using our Module API.

Using scripts

Cypress command strings can be saved as scripts for reuse.

Let's say you often need to run Cypress E2E tests in headless mode using the Chrome browser. You can add the corresponding command cypress run --browser chrome to the scripts object in your package.json file and use the name e2e:chrome to identify it.

{
  "scripts": {
    "e2e:chrome": "cypress run --browser chrome"
  }
}

Running the script e2e:chrome as follows will run the command you defined:

npm

npm run e2e:chrome

Yarn

yarn e2e:chrome

pnpm

pnpm e2e:chrome

caution

Best Practice

Don't use cypress as the exact name of a script, especially if you use Yarn as package manager. When running commands on the Cypress binary (e.g. yarn cypress verify), Yarn will reference the script of the same name instead and Cypress CLI commands may not work as expected.

Extending script options

You do not have to define a new script for every variation of a command string you need. You can extend a script with additional options.

Let's say that when you ran the full set of tests with the script e2e:chrome it showed a failure in one test spec cypress/e2e/my-spec.cy.js. You corrected the problem and would like to re-run the tests only for the test spec which previously failed.

The option --spec allows you to specify which test specs to run, so you can add this to the command after the script name e2e:chrome:

npm

npm run e2e:chrome -- --spec "cypress/e2e/my-spec.cy.js"

Yarn

yarn e2e:chrome --spec "cypress/e2e/my-spec.cy.js"

pnpm

pnpm e2e:chrome --spec "cypress/e2e/my-spec.cy.js"

Refer to each package manager's documentation for full details of command and script usage:

• npm CLI
  When adding Cypress options after a script name called from npm, you need to pass the command's arguments using the -- string (see npm-run-script).
• Yarn CLI
• pnpm CLI

Commands

info

The prefix required to run cypress is not shown in the list of commands below. You need to add the prefix npx, yarn or pnpm to the command line, corresponding to the package manager you are using. See How to run commands.

cypress run

Runs Cypress tests to completion. By default, cypress run will run all tests headlessly.

cypress run [options]

Options

Option	Description
--auto-cancel-after-failures	Overrides the Cloud project-level configuration to set the failed test threshold for auto cancellation or to disable auto cancellation when recording to the Cloud
--browser, -b	Run Cypress in the browser with the given name. If a filesystem path is supplied, Cypress will attempt to use the browser at that path.
--ci-build-id	Specify a unique identifier for a run to enable grouping or parallelization.
--component	Run component tests
--config, -c	Specify configuration
--config-file, -C	Specify configuration file
--e2e	Run end to end tests (default)
--env, -e	Specify environment variables
--group	Group recorded tests together under a single run
--headed	Displays the browser instead of running headlessly
--headless	Hide the browser instead of running headed (default during cypress run)
--help, -h	Output usage information
--key, -k	Specify your secret record key
--no-exit	Keep Cypress open after tests in a spec file run
--no-runner-ui	Hides the Cypress Runner UI
--parallel	Run recorded specs in parallel across multiple machines
--port,-p	Override default port
--project, -P	Path to a specific project
--quiet, -q	If passed, Cypress output will not be printed to stdout. Only output from the configured Mocha reporter will print.
--record	Whether to record the test run
--reporter, -r	Specify a Mocha reporter
--reporter-options, -o	Specify Mocha reporter options
--runner-ui	Displays the Cypress Runner UI. Useful for when Test Replay is enabled and you would still like the Cypress Runner UI to be displayed for screenshots and video
--spec, -s	Specify the spec files to run
--tag, -t	Identify a run with a tag or tags

cypress run --auto-cancel-after-failures <autoCancelAfterFailures>

Note: Available in Cypress 12.6.0 and later

The "autoCancelAfterFailures" argument is the number of times tests can fail before the run is canceled

cypress run --record --key <<your_record_key>> --auto-cancel-after-failures 1

You can also specify false for the value to disable Auto Cancellation for the run:

cypress run --record --key <<your_record_key>> --auto-cancel-after-failures false

cypress run --browser <browser-name-or-path>

cypress run --browser chrome

The "browser" argument can be set to chrome, chromium, edge, electron, firefox to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you.

To launch non-stable browsers, add a colon and the desired release channel. For example, to launch Chrome Canary, use chrome:canary.

You can also choose a browser by supplying a path:

cypress run --browser /usr/bin/chromium

Having trouble with browser detection? Check out our troubleshooting guide

cypress run --ci-build-id <id>

This value should be automatically detected for most CI providers and is unnecessary to define unless Cypress is unable to determine it.

Typically, this is defined as an environment variable within your CI provider, defining a unique "build" or "run".

cypress run --ci-build-id BUILD_NUMBER

Only valid when providing a --group or --parallel flag. Read our parallelization documentation to learn more.

cypress run --config <config>

Set configuration values. Separate multiple values with commas. The values set here override any values set in your configuration file.

cypress run --config pageLoadTimeout=100000,watchForFileChanges=false

For more complex configuration objects, you may want to consider passing a JSON.stringified object surrounded by single quotes.

Here, we're passing in the configuration for component spec files.

cypress run --config '{"watchForFileChanges":false,"specPattern":["**/*.cy.js","**/*.cy.ts"]}'

info

Real World Example

The Cypress Real World App (RWA) uses --config flag to easily specify viewport sizes for responsive testing locally and in dedicated CI jobs.

Examples:

• npm scripts to run Cypress in mobile viewport.

• Circle CI job configuration for running test suites in mobile viewport.

cypress run --config-file <configuration-file>

You can specify a path to a file where Cypress configuration values are set.

cypress run --config-file tests/cypress.config.js

cypress run --env <env>

Set Cypress environment variables.

cypress run --env host=api.dev.local

Pass several variables using commas and no spaces. Numbers are automatically converted from strings.

cypress run --env host=api.dev.local,port=4222

Pass an object as a JSON in a string.

cypress run --env flags='{"feature-a":true,"feature-b":false}'

cypress run --group <name>

Group recorded tests together under a single run.

cypress run --group develop-env

You can add multiple groups to the same run by passing a different name. This can help distinguish groups of specs from each other.

cypress run --group admin-tests --spec 'cypress/e2e/admin/**/*'

cypress run --group user-tests --spec 'cypress/e2e/user/**/*'

Specifying the --ci-build-id may also be necessary.

Read more about grouping.

cypress run --headed

By default, Cypress will run tests headlessly during cypress run.

Passing --headed will force the browser to be shown. This matches how you run any browser via cypress open.

cypress run --headed

cypress run --no-exit

To prevent Cypress from exiting after running tests in a spec file, use --no-exit.

You can pass --headed --no-exit in order to view the command log or have access to developer tools after a spec has run.

cypress run --headed --no-exit

cypress run --no-runner-ui

To prevent Cypress from rendering the Runner UI, use --no-runner-ui.

cypress run --no-runner-ui

cypress run --parallel

Run recorded specs in parallel across multiple machines.

cypress run --record --parallel

You can additionally pass a --group flag so this shows up as a named group.

cypress run --record --parallel --group e2e-staging-specs

Read our parallelization documentation to learn more.

cypress run --port <port>

cypress run --port 8080

cypress run --project <project-path>

To see this in action we've set up an example repo to demonstrate this here.

cypress run --project ./some/nested/folder

cypress run --record --key <record-key>

Record your test results to Cypress Cloud. For this option to work you must first set up your project to record, make sure your projectId is set in your Cypress configuration file, and append your Record Key to the command.

cypress run --record --key <record_key>

If you set the Record Key as the environment variable CYPRESS_RECORD_KEY, you can omit the --key flag. You'd typically set this environment variable when running in Continuous Integration.

export CYPRESS_RECORD_KEY=abc-key-123

Now you can omit the --key flag.

cypress run --record

For more information on recording runs, see the Cypress Cloud setup instructions. For an in-depth explanation of how Cypress uses your record key and projectId to save your test results to Cypress Cloud, see the Identification section.

cypress run --reporter <reporter>

You can tests specifying a specific Mocha reporter.

cypress run --reporter json

You can specify reporter options using the --reporter-options <reporter-options> flag.

cypress run --reporter junit --reporter-options mochaFile=result.xml,toConsole=true

cypress run --runner-ui

To force Cypress to render the Runner UI, use --runner-ui.

cypress run --runner-ui

Useful for when Test Replay is enabled and you would still like the Runner UI to be rendered for screenshots and video.

cypress run --spec <spec>

Run tests specifying a single test file to run instead of all tests. The spec path should be an absolute path or can be relative to the current working directory.

cypress run --spec "cypress/e2e/examples/actions.cy.js"

Run tests within the folder matching the glob (Note: Using double quotes is strongly recommended).

cypress run --spec "cypress/e2e/login/**/*"

Run tests specifying multiple test files to run.

cypress run --spec "cypress/e2e/examples/actions.cy.js,cypress/e2e/examples/files.cy.js"

Use in combination with --project parameter. Imagine the Cypress tests are in a subfolder tests/e2e of the current project:

app/
  node_modules/
  package.json
  tests/
    unit/
    e2e/
      cypress/
        e2e/
          spec.cy.js
      cypress.config.js

If we are in the app folder, we can run the specs using the following command

cypress run --project tests/e2e --spec ./tests/e2e/cypress/e2e/spec.cy.js

cypress run --tag <tag>

Add a tag or tags to the recorded run. This can be used to help identify separate runs when displayed in Cypress Cloud.

cypress run  --record --tag "staging"

Give a run multiple tags.

cypress run --record --tag "production,nightly"

Cypress Cloud will display any tags sent with the appropriate run.

Exit code

When Cypress finishes running tests, it exits. If there are no failed tests, the exit code will be 0.

## All tests pass
$ cypress run
...
                                        Tests  Passing  Failing
    ✔  All specs passed!      00:16       17       17        0

## print exit code on Mac or Linux
$ echo $?
0

If there are any test failures, then the exit code will match the number of tests that failed.

## Spec with two failing tests
$ cypress run
...
                                        Tests  Passing  Failing
    ✖  1 of 1 failed (100%)   00:22       17       14        2

## print exit code on Mac or Linux
$ echo $?
2

If Cypress could not run for some reason (for example if no spec files were found) then the exit code will be 1.

## No spec files found
$ cypress run --spec not-found.js
...
Can't run because no spec files were found.

We searched for any files matching this glob pattern:

not-found.js

## print exit code on Mac or Linux
$ echo $?
1

cypress open

Opens Cypress.

cypress open [options]

Options:

Options passed to cypress open will automatically be applied to the project you open. These persist on all projects until you quit Cypress. These options will also override values in the Cypress configuration file.

By passing --browser and --e2e or --component when launching a project, you can open Cypress and launch the browser at the same time. If passing the --browser flag alone, the browser will launch automatically after being guided through project and/or testing type selection. Otherwise, you will be guided through selecting a browser, project, and/or testing type.

Option	Description
--browser, -b	Run Cypress in the browser with the given name. If a filesystem path is supplied, Cypress will attempt to use the browser at that path.
--component	Open in component testing mode
--config, -c	Specify configuration
--config-file, -C	Specify configuration file
--detached, -d	Open Cypress in detached mode
--e2e	Open in end to end testing mode (default)
--env, -e	Specify environment variables
--global	Open in global mode
--help, -h	Output usage information
--port, -p	Override default port
--project, -P	Path to a specific project

cypress open --browser <browser-path>

By default, Cypress will automatically find and allow you to use the browsers installed on your system.

The "browser" option allows you to specify the path to a custom browser to use with Cypress:

cypress open --browser /usr/bin/chromium

If found, the specified browser will be added to the list of available browsers.

Currently, only browsers in the Chrome family (including the new Chromium-based Microsoft Edge and Brave) and Firefox are supported.

Having trouble launching a browser? Check out our troubleshooting guide

cypress open --config <config>

Set configuration values. Separate multiple values with a comma. The values set here override any values set in your configuration file.

cypress open --config pageLoadTimeout=100000,watchForFileChanges=false

For more complex configuration objects, you may want to consider passing a JSON.stringified object.

Here, we're passing in the configuration for component spec files.

cypress open --config "{\"watchForFileChanges\":false,\"specPattern\":[\"**/*.cy.js\",\"**/*.cy.ts\"]}"

cypress open --config-file <configuration-file>

You can specify a path to a file where Cypress configuration values are set.

cypress open --config-file tests/cypress.config.js

cypress open --env <env>

Set Cypress environment variables.

cypress open --env host=api.dev.local

Pass several variables using commas and no spaces. Numbers are automatically converted from strings.

cypress open --env host=api.dev.local,port=4222

Pass an object as a JSON in a string.

cypress open --env flags='{"feature-a":true,"feature-b":false}'

cypress open --global

Opening Cypress in global mode is useful if you have multiple nested projects but want to share a single global installation of Cypress. In this case you can add each nested project to the Cypress in global mode, thus giving you a nice UI to switch between them.

cypress open --global

cypress open --port <port>

cypress open --port 8080

cypress open --project <project-path>

To see this in action we've set up an example repo to demonstrate this here.

cypress open --project ./some/nested/folder

cypress info

Prints information about Cypress and the current environment such as:

• A list of browsers Cypress detected on the machine.
• Any environment variables that control proxy configuration.
• Any environment variables that start with the CYPRESS prefix (with sensitive variables like record key masked for security).
• The location where run-time data is stored.
• The location where the Cypress binary is cached.
• Operating system information.
• System memory including free space.

cypress info
Displaying Cypress info...

Detected 2 browsers installed:

1. Chrome
  - Name: chrome
  - Channel: stable
  - Version: 79.0.3945.130
  - Executable: /path/to/google-chrome
  - Profile: /user/profile/folder/for/google-chrome

2. Firefox Nightly
  - Name: firefox
  - Channel: nightly
  - Version: 74.0a1
  - Executable: /path/to/firefox

Note: to run these browsers, pass <name>:<channel> to the '--browser' field

Examples:
- cypress run --browser firefox:nightly
- cypress run --browser chrome

Learn More: https://on.cypress.io/launching-browsers

Proxy Settings: none detected
Environment Variables: none detected

Application Data: /path/to/app/data/cypress/cy/development
Browser Profiles: /path/to/app/data/cypress/cy/development/browsers
Binary Caches: /user/profile/path/.cache/Cypress

Cypress Version: 4.1.0
System Platform: darwin (19.2.0)
System Memory: 17.2 GB free 670 MB

Tip: set DEBUG environment variable to cypress:launcher:* when running cypress info to troubleshoot browser detection.

cypress verify

Verify that Cypress is installed correctly and is executable.

cypress verify
✔  Verified Cypress! /Users/jane/Library/Caches/Cypress/3.0.0/Cypress.app

To change the default timeout of 30 seconds, you can set the environment variable CYPRESS_VERIFY_TIMEOUT:

export CYPRESS_VERIFY_TIMEOUT=60000 # wait for 60 seconds
cypress verify

Note that the cypress verify command is executed as part of the cypress open and cypress run commands. The CYPRESS_VERIFY_TIMEOUT environment variable should be provided for those commands if you wish to modify the timeout duration.

cypress version

Prints the installed Cypress binary version, the Cypress package version, the version of Electron used to build Cypress, and the bundled Node version.

In most cases the binary and the package versions will be the same, but they could be different if you have installed a different version of the package and for some reason failed to install the matching binary version.

cypress version
Cypress package version: 12.0.0
Cypress binary version: 12.0.0
Electron version: 21.0.0
Bundled Node version: 16.16.0

You can print each individual component's version number also.

cypress version --component package
12.0.0
cypress version --component binary
12.0.0
cypress version --component electron
21.0.0
cypress version --component node
16.16.0

cypress cache [command]

Commands for managing the global Cypress cache. The Cypress cache applies to all installs of Cypress across your machine, global or not.

cypress cache path

Print the path to the Cypress cache folder. You can change the path where the Cypress cache is located by following these instructions.

cypress cache path
/Users/jane/Library/Caches/Cypress

cypress cache list

Print all existing installed versions of Cypress. The output will be a table with cached versions and the last time the binary was used by the user, determined from the file's access time.

cypress cache list
┌─────────┬──────────────┐
│ version │ last used    │
├─────────┼──────────────┤
│ 3.0.0   │ 3 months ago │
├─────────┼──────────────┤
│ 3.0.1   │ 5 days ago   │
└─────────┴──────────────┘

You can calculate the size of every Cypress version folder by adding the --size argument to the command. Note that calculating the disk size can be slow.

cypress cache list --size
┌─────────┬──────────────┬─────────┐
│ version │ last used    │ size    │
├─────────┼──────────────┼─────────┤
│ 5.0.0   │ 3 months ago │ 425.3MB │
├─────────┼──────────────┼─────────┤
│ 5.3.0   │ 5 days ago   │ 436.3MB │
└─────────┴──────────────┴─────────┘

cypress cache clear

Clear the contents of the Cypress cache. This is useful when you want Cypress to clear out all installed versions of Cypress that may be cached on your machine. After running this command, you will need to run cypress install before running Cypress again.

cypress cache clear

cypress cache prune

Deletes all installed Cypress versions from the cache except for the currently-installed version.

cypress cache prune

Debugging commands

Enable Debug Logs

If you are using macOS, Linux or Windows (Git Bash) and your package manager is npm, you can run Cypress with debug logs using the following CLI command:

DEBUG=cypress:* npx cypress run

See Troubleshooting for more detailed instructions on options to generate debug logs, also with Yarn and pnpm package managers, and with Windows CMD and PowerShell terminal windows.

History

Version	Changes
12.6.0	Added --auto-cancel-after-failures flag to cypress run
5.4.0	Added prune subcommand to cypress cache
5.4.0	Added --size flag to cypress cache list subcommand
4.9.0	Added --quiet flag to cypress run