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.

Option	Type	Description
`autoCancelAfterFailures`	number \| false	Specify the number of failures to cancel a run being recorded to the Cloud or `false` to disable auto-cancellation.
`browser`	string	Specify different browser to run tests in, either by name or by filesystem path
`ciBuildId`	string	Specify a unique identifier for a run to enable grouping or parallelization
`config`	object	Specify configuration
`configFile`	string	Path to the configuration file to be used.
`env`	object	Specify environment variables
`group`	string	Group recorded tests together under a single run
`headed`	boolean	Displays the browser instead of running headlessly
`headless`	boolean	Hide the browser instead of running headed (default during `cypress run`)
`key`	string	Specify your secret record key
`exit`	boolean	Whether to close Cypress after all tests run
`parallel`	boolean	Run recorded specs in parallel across multiple machines
`port`	number	Override default port
`project`	string	Path to a specific project
`quiet`	boolean	If passed, Cypress output will not be printed to `stdout`. Only output from the configured Mocha reporter will print.
`record`	boolean	Whether to record the test run
`reporter`	string	Specify a Mocha reporter
`reporterOptions`	object	Specify Mocha reporter options
`runnerUi`	boolean	Whether to display the Cypress Runner UI. Defaults to `false` when Test Replay is enabled. Otherwise defaults to `true`.
`slowTestThreshold`	number	Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter.
`spec`	string	Specify the specs to run, see examples below
`tag`	string	Identify a run with a tag or tags
`testingType`	string	Specify 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, the Promise resolves with the test results. 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)
  }

  // print test results and 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.

Option	Type	Description
`browser`	string	Specify a filesystem path to a custom browser
`config`	object	Specify configuration
`configFile`	string	Path to the configuration file to be used.
`detached`	boolean	Open Cypress in detached mode
`env`	object	Specify environment variables
`global`	boolean	Run in global mode
`port`	number	Override default port
`project`	string	Path to a specific project
`testingType`	string	Specify 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.

We use CLI parsing and calling cypress.run to repeat tests to find flaky tests and to validate test numbers after a test run. Read Wrap Cypress Using npm Module API for more examples.

History

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

cypress.run()​

Options​

Examples​

Run a single spec file​

Run specs using wildcard​

Programmatically control which browser to run​

Use modern syntax​

Results​

Handling errors​

cypress.open()​

Options​

Example​

cypress.cli​

parseRunArguments()​

History​

Contents

`cypress.run()`

Options

Examples

Run a single spec file

Run specs using wildcard

Programmatically control which browser to run

Use modern syntax

Results

Handling errors

`cypress.open()`

Options

Example

`cypress.cli`

`parseRunArguments()`

History