{
  "doc": {
    "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": "/llm/markdown/app/references/module-api.md",
    "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c",
    "updated_at": "2026-05-07T17:44:31.931Z",
    "headings": [
      {
        "id": "app/references/module-api#module-api",
        "text": "Module API",
        "level": 1
      },
      {
        "id": "app/references/module-api#cypress-run",
        "text": "cypress.run()",
        "level": 2
      },
      {
        "id": "app/references/module-api#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "app/references/module-api#examples",
        "text": "Examples",
        "level": 3
      },
      {
        "id": "app/references/module-api#run-a-single-spec-file",
        "text": "Run a single spec file",
        "level": 4
      },
      {
        "id": "app/references/module-api#run-specs-using-wildcard",
        "text": "Run specs using wildcard",
        "level": 4
      },
      {
        "id": "app/references/module-api#programmatically-control-which-browser-to-run",
        "text": "Programmatically control which browser to run",
        "level": 4
      },
      {
        "id": "app/references/module-api#use-modern-syntax",
        "text": "Use modern syntax",
        "level": 4
      },
      {
        "id": "app/references/module-api#results",
        "text": "Results",
        "level": 3
      },
      {
        "id": "app/references/module-api#handling-errors",
        "text": "Handling errors",
        "level": 3
      },
      {
        "id": "app/references/module-api#cypress-open",
        "text": "cypress.open()",
        "level": 2
      },
      {
        "id": "app/references/module-api#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "app/references/module-api#example",
        "text": "Example",
        "level": 3
      },
      {
        "id": "app/references/module-api#cypress-cli",
        "text": "cypress.cli",
        "level": 2
      },
      {
        "id": "app/references/module-api#parserunarguments",
        "text": "parseRunArguments()",
        "level": 3
      },
      {
        "id": "app/references/module-api#history",
        "text": "History",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Module API"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Send a notification about failing tests with included screenshot images"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Rerun a single failing spec file"
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Kick off other builds or scripts"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Yarn Plug'n'Play"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "To run Cypress via Node.js in a "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://yarnpkg.com/features/pnp",
            "children": [
              {
                "type": "text",
                "value": "Yarn Plug'n'Play"
              }
            ]
          },
          {
            "type": "text",
            "value": " environment, use "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://yarnpkg.com/cli/node",
            "children": [
              {
                "type": "text",
                "value": "yarn node"
              }
            ]
          },
          {
            "type": "text",
            "value": " instead of "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://nodejs.org/en/learn/command-line/run-nodejs-scripts-from-the-command-line",
            "children": [
              {
                "type": "text",
                "value": "node"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "`cypress.run()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Runs Cypress tests via Node.js and resolve with all test results. See the "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/cypress-example-recipes#fundamentals",
            "children": [
              {
                "type": "text",
                "value": "Cypress Module API recipe"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// e2e-run-tests.jsconst cypress = require('cypress')cypress.run({  reporter: 'junit',  browser: 'chrome',  config: {    baseUrl: 'http://localhost:8080',    video: true,  },  env: {    apiKey: 'secret-key-12345',  },  expose: {    apiVersion: 'v2',  },})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then run Cypress by running the following in your terminal or an npm script:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "node e2e-run-tests.js"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Options"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Just like the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/command-line.md",
            "children": [
              {
                "type": "text",
                "value": "Command Line options"
              }
            ]
          },
          {
            "type": "text",
            "value": " for `cypress run`, you can pass options that modify how Cypress runs."
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Option"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Type"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`autoCancelAfterFailures`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "number"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "false"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify the number of failures to cancel a run being recorded to the Cloud or `false` to disable auto-cancellation."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`browser`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify different browser to run tests in, either by name or by filesystem path"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`ciBuildId`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify a unique identifier for a run to enable "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs",
                    "children": [
                      {
                        "type": "text",
                        "value": "grouping"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " or "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "parallelization"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`config`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "configuration"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`configFile`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Path to the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Configuration-File",
                    "children": [
                      {
                        "type": "text",
                        "value": "configuration file"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to be used."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`env`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify secret "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/guides/environment-variables.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "environment variables"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`expose`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify public "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/cypress-api/expose.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "exposed variables"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`group`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md#Grouping-test-runs",
                    "children": [
                      {
                        "type": "text",
                        "value": "Group"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " recorded tests together under a single run"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`headed`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Displays the browser instead of running headlessly"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`headless`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Hide the browser instead of running headed (default during `cypress run`)"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`key`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify your secret record key"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`exit`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether to close Cypress after all tests run"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`parallel`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Run recorded specs in "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "parallel"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " across multiple machines"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`port`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "number"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Override default port"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`posixExitCodes`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Exit with a POSIX-compliant exit code rather than the number of failed tests."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`project`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Path to a specific project"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`quiet`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "If passed, Cypress output will not be printed to `stdout`. Only output from the configured "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/tooling/reporters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Mocha reporter"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " will print."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`record`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether to record the test run"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`reporter`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify a "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/tooling/reporters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Mocha reporter"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`reporterOptions`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/tooling/reporters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Mocha reporter"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " options"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`runnerUi`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Whether to display the Cypress Runner UI. Defaults to `false` when "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/cloud/features/test-replay.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Test Replay"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " is enabled. Otherwise defaults to `true`."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`slowTestThreshold`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "number"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Time, in milliseconds, to consider a test \"slow\" during `cypress run`. A slow test will display in orange text in the default reporter."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`spec`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify the specs to run, see examples below"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`tag`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Identify a run with a tag or tags"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`testingType`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify the type of tests to execute; either `e2e` or `component`. Defaults to `e2e`"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Run a single spec file"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Here is an example of programmatically running a spec file. Note that the file path is relative to the current working directory."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// e2e-run-tests.jsconst 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)  })"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then run Cypress by running the following in your terminal or an npm script:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "node e2e-run-tests.js"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Run specs using wildcard"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can pass a wildcard pattern to run all matching spec files"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const cypress = require('cypress')cypress.run({  // the wildcard path is relative to the current working directory  spec: './cypress/e2e/**/api*.js',})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Programmatically control which browser to run"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// run 'node cypress-chrome.js'const cypress = require('cypress')cypress.run({  spec: './cypress/e2e/**/chrome-test*.js',  browser: 'chrome',})"
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// run 'node cypress-firefox.js'const cypress = require('cypress')cypress.run({  spec: './cypress/e2e/**/firefox-test*.js',  browser: 'firefox',})"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Use modern syntax"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If your Node version allows you can use the modern `async / await` syntax to wait for the Promise returned by the `cypress.run` method."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const cypress = require('cypress');(async () => {  const results = await cypress.run()  // use the results object})()"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Results"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cypress.run()` returns a `Promise` that resolves with an object containing the tests results. A typical run could return something like this:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"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,}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can find the TypeScript definition for the results object in the "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/cypress/tree/develop/cli/types",
            "children": [
              {
                "type": "text",
                "value": "`cypress/cli/types` folder"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Handling errors"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "{  \"failures\": 1,    // non-zero number  \"message\": \"...\"  // error message}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In order to handle these possible errors, you can add a `catch` to `cypress.run()`:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// e2e-run-tests.jsconst 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)})"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "`cypress.open()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Open Cypress tests via Node.js."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// e2e-open-tests.jsconst cypress = require('cypress')cypress.open({  config: {    baseUrl: 'http://localhost:8080',  },  env: {    apiKey: 'secret-key-12345',  },  expose: {    apiVersion: 'v2',  },})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then open Cypress by running the following in your terminal or an npm script:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "node e2e-open-tests.js"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Options"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Just like the "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/command-line.md",
            "children": [
              {
                "type": "text",
                "value": "Command Line options"
              }
            ]
          },
          {
            "type": "text",
            "value": ", you can pass options that modify how Cypress runs."
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Option"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Type"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Description"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`browser`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify a filesystem path to a custom browser"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`config`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "configuration"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`configFile`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Path to the "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/configuration.md#Configuration-File",
                    "children": [
                      {
                        "type": "text",
                        "value": "configuration file"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to be used."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`detached`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Open Cypress in detached mode"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`env`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify secret "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/guides/environment-variables.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "environment variables"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`expose`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "object"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify public "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/cypress-api/expose.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "exposed variables"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`global`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "boolean"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Run in global mode"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`port`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "number"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Override default port"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`project`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Path to a specific project"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`testingType`"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "string"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Specify the type of tests to execute; either `e2e` or `component`. Defaults to `e2e`"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Example"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// e2e-open-tests.jsconst cypress = require('cypress')cypress.open({})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then open Cypress by running the following in your terminal or an npm script:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "node e2e-open-tests.js"
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "`cypress.cli`"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "`parseRunArguments()`"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "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."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// wrapper.jsconst cypress = require('cypress')const runOptions = await cypress.cli.parseRunArguments(process.argv.slice(2))const results = await cypress.run(runOptions)// process the \"cypress.run()\" results"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "An example use running from your terminal could be:"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "node ./wrapper cypress run --browser chrome --config ..."
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note: the arguments passed to `parseRunArguments` should start with `cypress run`."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#15-10-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "15.10.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `expose` configuration option."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#15-4-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "15.4.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `posixExitCodes` to run options."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#12-6-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "12.6.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `autoCancelAfterFailures` to run options."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#10-0-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "10.0.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`slowTestThreshold` is now scoped to each testing type."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#8-7-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "8.7.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `slowTestThreshold` configuration option."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#7-3-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "7.3.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `testingType` configuration option."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#5-0-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "5.0.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Test results returned from `cypress.run()` changed."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#4-11-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "4.11.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `cypress.cli` with `parseRunArguments` function."
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#4-9-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "4.9.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `quiet` option to `cypress.run()`"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 2036
}