--- id: app/references/module-api title: 'Module API: How to run Cypress via Node.js' description: >- Require Cypress as a node module from your application under test and run Cypress via Node.js. section: app source_path: docs/app/references/module-api.mdx version: 1375fa62d5875962138c8c43f27d7e1235a504a5 updated_at: '2026-04-29T19:28:48.012Z' --- # 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 Yarn Plug'n'Play To run Cypress via Node.js in a [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp) environment, use [yarn node](https://yarnpkg.com/cli/node) instead of [node](https://nodejs.org/en/learn/command-line/run-nodejs-scripts-from-the-command-line). ## cypress.run() Runs Cypress tests via Node.js and resolve with all test results. See the [Cypress Module API recipe](https://github.com/cypress-io/cypress-example-recipes#fundamentals). ```javascript // e2e-run-tests.js const cypress = require('cypress') cypress.run({ reporter: 'junit', browser: 'chrome', config: { baseUrl: 'http://localhost:8080', video: true, }, env: { apiKey: 'secret-key-12345', }, expose: { apiVersion: 'v2', }, }) ``` You can then run Cypress by running the following in your terminal or an npm script: ```shell node e2e-run-tests.js ``` ### Options Just like the [Command Line options](/llm/markdown/app/references/command-line.md) 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](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs) or [parallelization](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) | | `config` | *object* | Specify [configuration](/llm/markdown/app/references/configuration.md) | | `configFile` | *string* | Path to the [configuration file](/llm/markdown/app/references/configuration.md#Configuration-File) to be used. | | `env` | *object* | Specify secret [environment variables](/llm/markdown/app/guides/environment-variables.md) | | `expose` | *object* | Specify public [exposed variables](/llm/markdown/api/cypress-api/expose.md) | | `group` | *string* | [Group](/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs) 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](/llm/markdown/cloud/features/smart-orchestration/parallelization.md) across multiple machines | | `port` | *number* | Override default port | | `posixExitCodes` | *boolean* | Exit with a POSIX-compliant exit code rather than the number of failed tests. | | `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](/llm/markdown/app/tooling/reporters.md) will print. | | `record` | *boolean* | Whether to record the test run | | `reporter` | *string* | Specify a [Mocha reporter](/llm/markdown/app/tooling/reporters.md) | | `reporterOptions` | *object* | Specify [Mocha reporter](/llm/markdown/app/tooling/reporters.md) options | | `runnerUi` | *boolean* | Whether to display the Cypress Runner UI. Defaults to `false` when [Test Replay](/llm/markdown/cloud/features/test-replay.md) 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. ```js // 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: ```shell node e2e-run-tests.js ``` #### Run specs using wildcard You can pass a wildcard pattern to run all matching spec files ```js 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. ```js // run 'node cypress-chrome.js' const cypress = require('cypress') cypress.run({ spec: './cypress/e2e/**/chrome-test*.js', browser: 'chrome', }) ``` ```js // 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. ```js 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: ```json { "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](https://github.com/cypress-io/cypress/tree/develop/cli/types). ### Handling errors Even when tests fail or a spec errors, the `Promise` resolves with the test results. If a spec errors, the error message will be in the `runs` array under the `error` field. 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 ```js { "failures": 1, // non-zero number "message": "..." // error message } ``` In order to handle these possible errors, you can add a `catch` to `cypress.run()`: ```js // 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) } // 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. ```javascript // e2e-open-tests.js const cypress = require('cypress') cypress.open({ config: { baseUrl: 'http://localhost:8080', }, env: { apiKey: 'secret-key-12345', }, expose: { apiVersion: 'v2', }, }) ``` You can then open Cypress by running the following in your terminal or an npm script: ```shell node e2e-open-tests.js ``` ### Options Just like the [Command Line options](/llm/markdown/app/references/command-line.md), 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](/llm/markdown/app/references/configuration.md) | | `configFile` | *string* | Path to the [configuration file](/llm/markdown/app/references/configuration.md#Configuration-File) to be used. | | `detached` | *boolean* | Open Cypress in detached mode | | `env` | *object* | Specify secret [environment variables](/llm/markdown/app/guides/environment-variables.md) | | `expose` | *object* | Specify public [exposed variables](/llm/markdown/api/cypress-api/expose.md) | | `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 ```javascript // 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: ```shell 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. ```javascript // 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: ```shell node ./wrapper cypress run --browser chrome --config ... ``` **Note:** the arguments passed to `parseRunArguments` should start with `cypress run`. ## History | Version | Changes | | ------------------------------------------------------------ | ------------------------------------------------------- | | [15.10.0](/llm/markdown/app/references/changelog.md#15-10-0) | Added `expose` configuration option. | | [15.4.0](/llm/markdown/app/references/changelog.md#15-4-0) | Added `posixExitCodes` to run options. | | [12.6.0](/llm/markdown/app/references/changelog.md#12-6-0) | Added `autoCancelAfterFailures` to run options. | | [10.0.0](/llm/markdown/app/references/changelog.md#10-0-0) | `slowTestThreshold` is now scoped to each testing type. | | [8.7.0](/llm/markdown/app/references/changelog.md#8-7-0) | Added `slowTestThreshold` configuration option. | | [7.3.0](/llm/markdown/app/references/changelog.md#7-3-0) | Added `testingType` configuration option. | | [5.0.0](/llm/markdown/app/references/changelog.md#5-0-0) | Test results returned from `cypress.run()` changed. | | [4.11.0](/llm/markdown/app/references/changelog.md#4-11-0) | Added `cypress.cli` with `parseRunArguments` function. | | [4.9.0](/llm/markdown/app/references/changelog.md#4-9-0) | Added `quiet` option to `cypress.run()` |