Command Line
What you'll learn
- How to run Cypress from the command line
- How to specify which spec files to run
- How to launch other browsers
- How to record your tests to the Dashboard
Installation
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 alternatively require and run Cypress as a node module using our Module API.
For brevity we've omitted the full path to the cypress executable in each command's documentation.
To run a command, you'll need to prefix each command in order to properly locate the cypress executable.
$(npm bin)/cypress run
...or...
./node_modules/.bin/cypress run
...or... (requires npm@5.2.0 or greater)
npx cypress run
...or by using Yarn...
yarn cypress run
You may find it easier to add the cypress command to the scripts
object in
your package.json
file and call it from an
npm run
script.
When calling a command using npm run
, you need to pass the command's arguments
using the --
string. For example, if you have the following command defined in
your package.json
{
"scripts": {
"cy:run": "cypress run"
}
}
...and want to run tests from a single spec file and record the results on the Dashboard, the command should be:
npm run cy:run -- --record --spec "cypress/integration/my-spec.js"
If you are using the npx tool, you can invoke the locally installed Cypress tool directly:
npx cypress run --record --spec "cypress/integration/my-spec.js"
Read how we typically organize and execute npm scripts in the blog post How I Organize my npm Scripts.
Commands
cypress run
Runs Cypress tests to completion. By default, cypress run
will run all tests
headlessly.
cypress run [options]
Options
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 a comma. The values set here override any values set in your configuration file.
cypress run --config pageLoadTimeout=100000,watchForFileChanges=false
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 <config-file>
You can specify a path to a JSON file where
configuration values are set. This defaults
to cypress.json
.
cypress run --config-file tests/cypress-config.json
You can pass false
to disable the use of a configuration file entirely.
cypress run --config-file false
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/integration/admin/**/*'
cypress run --group user-tests --spec 'cypress/integration/user/**/*'
Specifying the --ci-build-id
may also be necessary.
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 the Cypress Test Runner 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 --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 video of tests running after setting up your project to record. After setting up your project you will be given a Record Key.
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
You can read more about recording runs here.
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 --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 relative to the current working directory.
cypress run --spec "cypress/integration/examples/actions.spec.js"
Run tests within the folder matching the glob (Note: Using double quotes is strongly recommended).
cypress run --spec "cypress/integration/login/**/*"
Run tests specifying multiple test files to run.
cypress run --spec "cypress/integration/examples/actions.spec.js,cypress/integration/examples/files.spec.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/
integration/
spec.js
cypress.json
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/integration/spec.js
cypress run --tag <tag>
Add a tag or tags to the recorded run. This can be used to help identify separate run when displayed in the Dashboard.
cypress run --record --tag "staging"
Give a run multiple tags.
cypress run --record --tag "production,nightly"
The Dashboard 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 the Cypress Test Runner.
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 the Cypress Test Runner.
These options will also override values in your configuration file
(cypress.json
by default).
Option | Description |
---|---|
--browser , -b | Path to a custom browser to be added to the list of available browsers in Cypress |
--config , -c | Specify configuration |
--config-file , -C | Specify configuration file |
--detached , -d | Open Cypress in detached mode |
--env , -e | Specify environment variables |
--global | Run 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 in the Cypress Test Runner.
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
cypress open --config-file <config-file>
You can specify a path to a JSON file where
configuration values are set. This defaults
to cypress.json
.
cypress open --config-file tests/cypress-config.json
You can pass false
to disable the use of a configuration file entirely.
cypress open --config-file false
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: 6.0.0
Cypress binary version: 6.0.0
Electron version: 10.1.5
Bundled Node version: 12.14.1
You can print each individual component's version number also.
cypress version --component package
6.0.0
cypress version --component binary
6.0.0
cypress version --component electron
10.1.5
cypress version --component node
12.14.1
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
Cypress is built using the debug module.
That means you can receive helpful debugging output by running Cypress with this
turned on prior to running cypress open
or cypress run
.
On Mac or Linux:
DEBUG=cypress:* cypress open
DEBUG=cypress:* cypress run
On Windows:
set DEBUG=cypress:*
cypress run
Cypress is a rather large and complex project involving a dozen or more submodules, and the default output can be overwhelming.
To filter debug output to a specific module
DEBUG=cypress:cli cypress run
DEBUG=cypress:launcher cypress run
...or even a 3rd level deep submodule
DEBUG=cypress:server:project cypress run
History
Version | Changes |
---|---|
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 |