Cypress Module API: Integration and Automation

Last update on July 18 2024 13:07:28 (UTC/GMT +8 hours)

This tutorial will cover how you can require Cypress as a node module from your application under test. The Module API is useful when you want to access test results directly after the run. This workflow will enable you to:

Send a notification about failing tests, and include screenshot images
Rerun a single spec file
Kick off other builds or scripts

cypress.run()

This command will run the Cypress tests and then resolve with all the test results.

Options:

You can pass options that modify how Cypress runs just like the Command Line options for cypress run.

Option	Type	Description
browser	string	This option is used to specify different browser to run tests in, either by name or by filesystem path.
ciBuildId	string	This option is used to specify a unique identifier for a run to enable grouping or parallelization.
config	object	This is used to specify configuration.
configFile	string / boolean	This is used to define the path to the config file to be used. If false is passed, no config file is used.
env	object	The env option is used to specify the environment variables.
group	string	This is used to group recorded tests under a single run.
headed	boolean	This option will display the browser instead of running headlessly (default for Firefox and Chromium-based browsers)
headless	boolean	Hides the browser instead of running headed (defaults for Electron)
key	string	This is used to specify your secret record key
exit	boolean	Determines whether to close Cypress after all tests run.
parallel	boolean	This will run recorded specs in parallel across multiple machines.
port	number	Used to override the default port
project	string	This option is used to specify the path to a specific project.
quiet	boolean	If passed this option, The Cypress output will not be printed to stdout. Only the output from the configured Mocha reporter will print.
record	boolean	This option determines whether a test run will be recorded.
reporter	string	Used to specify a Mocha reporter
reporterOptions	object	Used to specify the Mocha reporter options
spec	string	This option will specify the specs to run.
tag	string	Used to identify a run using a tag or tags.

Here is an example of how to run a spec file programmatically:

'''const cypress = require('cypress')

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

The cypress.run line will return a Promise that resolves with an object containing the test results. A typical run might return something like this:

'''{
  "cypressVersion": "4.0.7",
  "endedTestsAt": "2020-06-11T17:53:35.675Z",
  "browserName": "electron",
  "browserPath": "path/to/browser",
  "browserVersion": "60.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/aryanvikta/app/cypress/videos/random.mp4"
  }],
  "runUrl": "https://dashboard.cypress.io/projects/de/runs/12",
  "startedTestsAt": "2020-06-11T17:53:35.463Z",
  "totalDuration": 212,
  "totalFailed": 1,
  "totalPassed": 0,
  "totalPending": 0,
  "totalSkipped": 12,
  "totalSuites": 8,
  "totalTests": 13,
}'''

Even if the tests fail, the Promise will still resolve with the test results. The Promise will only be rejected when Cypress cannot run for some reasons; for instance, if a binary has not been installed or if it cannot find a module dependency. In such case, the Promise is rejected with a detailed error.

cypress.open()

Options

You can pass options that modify how Cypress runs just like the Command Line options for cypress run.

Option	Type	Description
browser	string	Used to specify a filesystem path to a custom browser
config	object	This option is specify your configuration
configFile	string / boolean	This option defines the path to the config file that is used, if you set it to false, your run will not use a config file
detached	boolean	This is used to open Cypress in detached mode
env	object	Used to specify environment variables
global	boolean	This is used to run your test in a global mode
port	number	This option is used to override the default port
project	string	This option defines the path to a specific project

Here is an example:

'''const cypress = require('cypress')

cypress.open()'''