🎉We’re thrilled to announce GitHub Integration for the Cypress Dashboard!

Learn More

Module API

Improve this doc

You can require Cypress as a node module from your application under test. This can be useful when you want to 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

cypress.run()

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

Options:

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

Option Type Description
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
env Object Specify environment variables
group String Group recorded tests together under a single run
headed Boolean Display the Electron browser instead of running headlessly
key String Specify your secret record key
noExit Boolean Keep Cypress open 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
record Boolean Whether to record the test run
reporter String Specify a Mocha reporter
reporterOptions Object Specify Mocha reporter options
spec String Specify the specs to run
const cypress = require('cypress')

cypress.run({
  reporter: 'junit',
  browser: 'chrome',
  config: {
    baseUrl: 'http://localhost:8080',
    chromeWebSecurity: false,
    video: true,
  },
  env: {
    foo: 'bar',
    baz: 'quux',
  }
})

Example:

Here is an example of programmatically running a spec file:

const cypress = require('cypress')

cypress.run({
  spec: './cypress/integration/examples/actions.spec.js'
})
.then((results) => {
  console.log(results)
})
.catch((err) => {
  console.error(err)
})

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,
    "hooks": [...],
    "reporter": "spec",
    "reporterStats": {...},
    "screenshots": [],
    "shouldUploadVideo": true,
    "spec": {...},
    "stats": {...},
    "tests": [...],
    "video": "User/janelane/my-app/cypress/videos/abc123.mp4"
  }],
  "runUrl": "https://dashboard.cypress.io/projects/def456/runs/12",
  "startedTestsAt": "2018-07-11T17:53:35.463Z",
  "totalDuration": 212,
  "totalFailed": 1,
  "totalPassed": 0,
  "totalPending": 0,
  "totalSkipped": 12,
  "totalSuites": 8,
  "totalTests": 13,
}

Find the TypeScript definition for the results object in the cypress/cli/types folder.

Even when tests fail, the Promise still 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.

cypress.open()

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 Options Specify configuration
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

Example

const cypress = require('cypress')

cypress.open()