Skip to main content

Module API

You can require Cypress as a node module from your application under test and run Cypress via Node.js. This can be useful when you want access to the test results directly after the run. With this workflow, for example, you can:

  • Send a notification about failing tests with included screenshot images
  • Rerun a single failing spec file
  • Kick off other builds or scripts
info
Yarn Plug'n'Play

To run Cypress via Node.js in a Yarn Plug'n'Play environment, use yarn node instead of node.

cypress.run()​

Runs Cypress tests via Node.js and resolve with all test results. See the Cypress Module API recipe.

// e2e-run-tests.js
const cypress = require('cypress')

cypress.run({
reporter: 'junit',
browser: 'chrome',
config: {
baseUrl: 'http://localhost:8080',
video: true,
},
env: {
login_url: '/login',
products_url: '/products',
},
})

You can then run Cypress by running the following in your terminal or an npm script:

node e2e-run-tests.js

Options​

Just like the Command Line options for cypress run, you can pass options that modify how Cypress runs.

OptionTypeDescription
autoCancelAfterFailuresnumber | falseSpecify the number of failures to cancel a run being recorded to the Cloud or false to disable auto-cancellation.
browserstringSpecify different browser to run tests in, either by name or by filesystem path
ciBuildIdstringSpecify a unique identifier for a run to enable grouping or parallelization
configobjectSpecify configuration
configFilestringPath to the configuration file to be used.
envobjectSpecify environment variables
groupstringGroup recorded tests together under a single run
headedbooleanDisplays the browser instead of running headlessly
headlessbooleanHide the browser instead of running headed (default during cypress run)
keystringSpecify your secret record key
exitbooleanWhether to close Cypress after all tests run
parallelbooleanRun recorded specs in parallel across multiple machines
portnumberOverride default port
projectstringPath to a specific project
quietbooleanIf passed, Cypress output will not be printed to stdout. Only output from the configured Mocha reporter will print.
recordbooleanWhether to record the test run
reporterstringSpecify a Mocha reporter
reporterOptionsobjectSpecify Mocha reporter options
runnerUibooleanWhether to display the Cypress Runner UI. Defaults to false when Test Replay is enabled. Otherwise defaults to true.
slowTestThresholdnumberTime, in milliseconds, to consider a test "slow" during cypress run. A slow test will display in orange text in the default reporter.
specstringSpecify the specs to run, see examples below
tagstringIdentify a run with a tag or tags
testingTypestringSpecify the type of tests to execute; either e2e or component. Defaults to e2e

Examples​

Run a single spec file​

Here is an example of programmatically running a spec file. Note that the file path is relative to the current working directory.

// e2e-run-tests.js
const cypress = require('cypress')

cypress
.run({
// the path is relative to the current working directory
spec: './cypress/e2e/examples/actions.cy.js',
})
.then((results) => {
console.log(results)
})
.catch((err) => {
console.error(err)
})

You can then run Cypress by running the following in your terminal or an npm script:

node e2e-run-tests.js

Run specs using wildcard​

You can pass a wildcard pattern to run all matching spec files

const cypress = require('cypress')

cypress.run({
// the wildcard path is relative to the current working directory
spec: './cypress/e2e/**/api*.js',
})

Programmatically control which browser to run​

You can pass a browser option to specify which browser to run tests in so that you can programmatically control which specs to run in each browser.

// run 'node cypress-chrome.js'
const cypress = require('cypress')

cypress.run({
spec: './cypress/e2e/**/chrome-test*.js',
browser: 'chrome',
})
// run 'node cypress-firefox.js'
const cypress = require('cypress')

cypress.run({
spec: './cypress/e2e/**/firefox-test*.js',
browser: 'firefox',
})

Use modern syntax​

If your Node version allows you can use the modern async / await syntax to wait for the Promise returned by the cypress.run method.

const cypress = require('cypress')

;(async () => {
const results = await cypress.run()
// use the results object
})()

Results​

cypress.run() returns a Promise that resolves with an object containing the tests results. A typical run could return something like this:

{
"cypressVersion": "3.0.2",
"endedTestsAt": "2018-07-11T17:53:35.675Z",
"browserName": "electron",
"browserPath": "path/to/browser",
"browserVersion": "59.0.3071.115",
"config": {...},
"osName": "darwin",
"osVersion": "14.5.0",
"runs": [{
"error": null,
"reporter": "spec",
"reporterStats": {...},
"spec": {...},
"stats": {
"suites": 1,
"tests": 1,
"passes": 0,
"pending": 0,
"skipped": 0,
"failures": 1,
"startedAt": "2020-08-05T08:38:37.589Z",
"endedAt": "2018-07-11T17:53:35.675Z",
"duration": 1171
},
"screenshots": [{
"name": null,
"takenAt": "2020-08-05T08:52:20.432Z",
"path": "User/janelane/my-app/cypress/screenshots/cy.js/test (failed).png",
"height": 720,
"width": 1280
}],
"tests": [{
"title": [ "test" ],
"state": "failed",
"displayError": "AssertionError: expected true to be false\n' +
' at Context.eval (...cypress/e2e/cy.js:5:21",
"attempts": [{
"state": "failed",
}],
}],
"video": "User/janelane/my-app/cypress/videos/abc123.mp4"
}],
"runUrl": "https://cloud.cypress.io/projects/def456/runs/12",
"startedTestsAt": "2018-07-11T17:53:35.463Z",
"totalDuration": 212,
"totalFailed": 1,
"totalPassed": 0,
"totalPending": 0,
"totalSkipped": 0,
"totalSuites": 1,
"totalTests": 1,
}

You can find the TypeScript definition for the results object in the cypress/cli/types folder.

Handling errors​

Even when tests fail or a spec errors, the Promise resolves with the test results. If a spec errors, the error message will be in the runs array under the error field. The Promise is only rejected if Cypress cannot run for some reason (for example if a binary has not been installed or it cannot find a module dependency). In that case, the Promise will be rejected with a detailed error.

There is a third option - Cypress could run, but the tests could not start for some reason. In that case the resolved value is an object with two fields

{
"failures": 1, // non-zero number
"message": "..." // error message
}

In order to handle these possible errors, you can add a catch to cypress.run():

// e2e-run-tests.js
const cypress = require('cypress')

cypress.run({...})
.then(result => {
if (result.failures) {
console.error('Could not execute tests')
console.error(result.message)
process.exit(result.failures)
}

// exit with the number of failed tests as exit code
process.exit(result.totalFailed)
})
.catch(err => {
console.error(err.message)
process.exit(1)
})

cypress.open()​

Open Cypress tests via Node.js.

// e2e-open-tests.js
const cypress = require('cypress')

cypress.open({
config: {
baseUrl: 'http://localhost:8080',
},
env: {
login_url: '/login',
products_url: '/products',
},
})

You can then open Cypress by running the following in your terminal or an npm script:

node e2e-open-tests.js

Options​

Just like the Command Line options, you can pass options that modify how Cypress runs.

OptionTypeDescription
browserstringSpecify a filesystem path to a custom browser
configobjectSpecify configuration
configFilestringPath to the configuration file to be used.
detachedbooleanOpen Cypress in detached mode
envobjectSpecify environment variables
globalbooleanRun in global mode
portnumberOverride default port
projectstringPath to a specific project
testingTypestringSpecify the type of tests to execute; either e2e or component. Defaults to e2e

Example​

// e2e-open-tests.js
const cypress = require('cypress')

cypress.open({})

You can then open Cypress by running the following in your terminal or an npm script:

node e2e-open-tests.js

cypress.cli​

parseRunArguments()​

If you are writing a tool that wraps around the cypress.run() command, you might want to parse user-supplied command line arguments using the same logic as cypress run uses. In that case, you can use the included parseRunArguments function.

// wrapper.js
const cypress = require('cypress')

const runOptions = await cypress.cli.parseRunArguments(process.argv.slice(2))
const results = await cypress.run(runOptions)
// process the "cypress.run()" results

An example use running from your terminal could be:

node ./wrapper cypress run --browser chrome --config ...

Note: the arguments passed to parseRunArguments should start with cypress run.

History​

VersionChanges
12.6.0Added autoCancelAfterFailures to run options.
10.0.0slowTestThreshold is now scoped to each testing type.
8.7.0Added slowTestThreshold configuration option.
7.3.0Added testingType configuration option.
5.0.0Test results returned from cypress.run() changed.
4.11.0Added cypress.cli with parseRunArguments function.
4.9.0Added quiet option to cypress.run()