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()