{
  "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": "1375fa62d5875962138c8c43f27d7e1235a504a5",
    "updated_at": "2026-04-29T19:28:48.012Z",
    "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\nrun Cypress via Node.js. This can be useful when you want access to the test\nresults 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\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://yarnpkg.com/features/pnp",
            "children": [
              {
                "type": "text",
                "value": "Yarn Plug'n'Play"
              }
            ]
          },
          {
            "type": "text",
            "value": " environment, use\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://yarnpkg.com/cli/node",
            "children": [
              {
                "type": "text",
                "value": "yarn node"
              }
            ]
          },
          {
            "type": "text",
            "value": " instead of\n"
          },
          {
            "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\n"
          },
          {
            "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": "javascript",
        "meta": null,
        "value": "// e2e-run-tests.js\nconst cypress = require('cypress')\n\ncypress.run({\n  reporter: 'junit',\n  browser: 'chrome',\n  config: {\n    baseUrl: 'http://localhost:8080',\n    video: true,\n  },\n  env: {\n    apiKey: 'secret-key-12345',\n  },\n  expose: {\n    apiVersion: 'v2',\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then run Cypress by running the following in your terminal or an npm\nscript:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "shell",
        "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\n`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 | 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\npath is relative to the current working directory."
          }
        ]
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "// e2e-run-tests.js\nconst cypress = require('cypress')\n\ncypress\n  .run({\n    // the path is relative to the current working directory\n    spec: './cypress/e2e/examples/actions.cy.js',\n  })\n  .then((results) => {\n    console.log(results)\n  })\n  .catch((err) => {\n    console.error(err)\n  })"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then run Cypress by running the following in your terminal or an npm\nscript:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "shell",
        "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": "js",
        "meta": null,
        "value": "const cypress = require('cypress')\n\ncypress.run({\n  // the wildcard path is relative to the current working directory\n  spec: './cypress/e2e/**/api*.js',\n})"
      },
      {
        "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\nyou can programmatically control which specs to run in each browser."
          }
        ]
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "// run 'node cypress-chrome.js'\nconst cypress = require('cypress')\n\ncypress.run({\n  spec: './cypress/e2e/**/chrome-test*.js',\n  browser: 'chrome',\n})"
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "// run 'node cypress-firefox.js'\nconst cypress = require('cypress')\n\ncypress.run({\n  spec: './cypress/e2e/**/firefox-test*.js',\n  browser: 'firefox',\n})"
      },
      {
        "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\nwait for the Promise returned by the `cypress.run` method."
          }
        ]
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "const cypress = require('cypress')\n\n;(async () => {\n  const results = await cypress.run()\n  // use the results object\n})()"
      },
      {
        "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\ntests results. A typical run could return something like this:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "json",
        "meta": null,
        "value": "{\n  \"cypressVersion\": \"3.0.2\",\n  \"endedTestsAt\": \"2018-07-11T17:53:35.675Z\",\n  \"browserName\": \"electron\",\n  \"browserPath\": \"path/to/browser\",\n  \"browserVersion\": \"59.0.3071.115\",\n  \"config\": {...},\n  \"osName\": \"darwin\",\n  \"osVersion\": \"14.5.0\",\n  \"runs\": [{\n    \"error\": null,\n    \"reporter\": \"spec\",\n    \"reporterStats\": {...},\n    \"spec\": {...},\n    \"stats\": {\n      \"suites\": 1,\n      \"tests\": 1,\n      \"passes\": 0,\n      \"pending\": 0,\n      \"skipped\": 0,\n      \"failures\": 1,\n      \"startedAt\": \"2020-08-05T08:38:37.589Z\",\n      \"endedAt\": \"2018-07-11T17:53:35.675Z\",\n      \"duration\": 1171\n    },\n    \"screenshots\": [{\n      \"name\": null,\n      \"takenAt\": \"2020-08-05T08:52:20.432Z\",\n      \"path\": \"User/janelane/my-app/cypress/screenshots/cy.js/test (failed).png\",\n      \"height\": 720,\n      \"width\": 1280\n    }],\n    \"tests\": [{\n      \"title\": [ \"test\" ],\n      \"state\": \"failed\",\n      \"displayError\": \"AssertionError: expected true to be false\\n' +\n      '    at Context.eval (...cypress/e2e/cy.js:5:21\",\n      \"attempts\": [{\n        \"state\": \"failed\",\n      }],\n    }],\n    \"video\": \"User/janelane/my-app/cypress/videos/abc123.mp4\"\n  }],\n  \"runUrl\": \"https://cloud.cypress.io/projects/def456/runs/12\",\n  \"startedTestsAt\": \"2018-07-11T17:53:35.463Z\",\n  \"totalDuration\": 212,\n  \"totalFailed\": 1,\n  \"totalPassed\": 0,\n  \"totalPending\": 0,\n  \"totalSkipped\": 0,\n  \"totalSuites\": 1,\n  \"totalTests\": 1,\n}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can find the TypeScript definition for the results object in the\n"
          },
          {
            "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.\nIf a spec errors, the error message will be in the `runs` array under the `error` field.\nThe `Promise` is only rejected if Cypress cannot run for some reason (for example if\na binary has not been installed or it cannot find a module dependency). In that\ncase, 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\nsome reason. In that case the resolved value is an object with two fields"
          }
        ]
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "{\n  \"failures\": 1,    // non-zero number\n  \"message\": \"...\"  // error message\n}"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "In order to handle these possible errors, you can add a `catch` to\n`cypress.run()`:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "js",
        "meta": null,
        "value": "// e2e-run-tests.js\nconst cypress = require('cypress')\n\ncypress.run({...})\n.then(result => {\n  if (result.failures) {\n    console.error('Could not execute tests')\n    console.error(result.message)\n    process.exit(result.failures)\n  }\n\n  // exit with the number of failed tests as exit code\n  process.exit(result.totalFailed)\n})\n.catch(err => {\n  console.error(err.message)\n  process.exit(1)\n})"
      },
      {
        "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": "javascript",
        "meta": null,
        "value": "// e2e-open-tests.js\nconst cypress = require('cypress')\n\ncypress.open({\n  config: {\n    baseUrl: 'http://localhost:8080',\n  },\n  env: {\n    apiKey: 'secret-key-12345',\n  },\n  expose: {\n    apiVersion: 'v2',\n  },\n})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then open Cypress by running the following in your terminal or an npm\nscript:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "shell",
        "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\noptions 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": "javascript",
        "meta": null,
        "value": "// e2e-open-tests.js\nconst cypress = require('cypress')\n\ncypress.open({})"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can then open Cypress by running the following in your terminal or an npm\nscript:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "shell",
        "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\nmight want to parse user-supplied command line arguments using the same logic as\n`cypress run` uses. In that case, you can use the included `parseRunArguments`\nfunction."
          }
        ]
      },
      {
        "type": "code",
        "lang": "javascript",
        "meta": null,
        "value": "// wrapper.js\nconst cypress = require('cypress')\n\nconst runOptions = await cypress.cli.parseRunArguments(process.argv.slice(2))\nconst results = await cypress.run(runOptions)\n// process the \"cypress.run()\" results"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "An example use running from your terminal could be:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "shell",
        "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\n`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": 2079
}