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 [email protected] or greater)
npx 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"
Commands
cypress run
Runs Cypress tests to completion. By default will run all tests headlessly in the Electron
browser.
cypress run [options]
Options
Option | Description |
---|---|
--browser , -b
| Specify a different browser to run tests in |
--ci-build-id | Specify a unique identifier for a run to enable grouping or parallelization. |
--config , -c
| Specify configuration |
--env , -e
| Specify environment variables |
--group | Group recorded tests together under a single run |
--headed | Display the Electron browser instead of running headlessly |
--help , -h
| Output usage information |
--key , -k
| Specify your secret record key |
--no-exit | Keep Cypress Test Runner open after tests in a spec file run |
--parallel | Run recorded specs in parallel across multiple machines |
--port ,-p
| Override default port |
--project , -P
| Path to a specific project |
--record | Whether to record the test run |
--reporter , -r
| Specify a Mocha reporter |
--reporter-options , -o
| Specify Mocha reporter options |
--spec , -s
| Specify the spec files to run |
cypress run --browser <browser-name-or-path>
cypress run --browser chrome
The “browser” argument can be set to “chrome”, “canary”, “chromium”, or “electron” to launch a browser detected on your system. Cypress will attempt to automatically find the installed browser for you.
You can also choose a browser by supplying a path:
cypress run --browser /usr/bin/chromium
Currently, only browsers in the Chrome family are supported.
Having trouble with browser detection? Check out the debugging 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>
Read more about environment variables and configuration.
cypress run --config pageLoadTimeout=100000,watchForFileChanges=false
cypress run --env <env>
Pass a single string variable.
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.shell
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.
shell
cypress run --group admin-tests --spec 'cypress/integration/admin/**/*
shell
cypress run --group user-tests --spec 'cypress/integration/user/**/*
Specifying the
--ci-build-id
may also be necessary.Read more about grouping.
cypress run --headed
By default, Cypress will run tests in Electron headlessly.
Passing --headed
will force Electron to be shown. This matches how you run Electron in interactive mode.
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>
By default, Cypress expects your cypress.json
to be found where your package.json
is. However, you can point Cypress to run in a different location.
This enables you to install Cypress in a top level node_modules
folder but run Cypress in a nested folder. This is also helpful when you have multiple Cypress projects in your repo.
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
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.
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"
cypress open
Opens the Cypress Test Runner in interactive mode.
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 cypress.json
.
Option | Description |
---|---|
--browser , -b
| Specify a different browser to run tests in |
--config , -c
| Specify configuration |
--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
Currently, only browsers in the Chrome family are supported.
Having trouble launching a browser? Check out the debugging guide
cypress open --config <config>
cypress open --config pageLoadTimeout=100000,watchForFileChanges=false
cypress open --env <env>
cypress open --env host=api.dev.local
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>
By default, Cypress expects your cypress.json
to be found where your package.json
is. However, you can point Cypress to run in a different location.
This enables you to install Cypress in a top level node_modules
folder but run Cypress in a nested folder. This is also helpful when you have multiple Cypress projects in your repo.
To see this in action we’ve set up an example repo to demonstrate this here.
cypress open --project ./some/nested/folder
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
cypress version
Output both the versions of the installed Cypress binary application and the npm module.
In most cases they will be the same, but they could be different if you have installed a different version of the npm package and for some reason could not install the matching binary.
cypress version Cypress package version: 3.0.0 Cypress binary version: 3.0.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.
cypress cache path /Users/jane/Library/Caches/Cypress
cypress cache list
Print all existing installed versions of Cypress. The output will be a space delimited list of version numbers.
cypress cache list 3.0.0 3.0.1 3.0.2
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
Debugging commands
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