w3resource

Module API


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