{ "doc": { "id": "app/references/launching-browsers", "title": "Launching Browsers in Cypress", "description": "Learn how to launch browsers in Cypress, customize the list of available browsers, and troubleshoot browser launching issues.", "section": "app", "source_path": "/llm/markdown/app/references/launching-browsers.md", "version": "24a73f8a97175663aaffd3b016289fb2a523a4ea", "updated_at": "2026-05-14T20:17:33.301Z", "headings": [ { "id": "app/references/launching-browsers#launching-browsers", "text": "Launching Browsers", "level": 1 }, { "id": "app/references/launching-browsers#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/references/launching-browsers#browsers", "text": "Browsers", "level": 2 }, { "id": "app/references/launching-browsers#browser-versions-supported", "text": "Browser versions supported", "level": 3 }, { "id": "app/references/launching-browsers#download-specific-chrome-version", "text": "Download specific Chrome version", "level": 3 }, { "id": "app/references/launching-browsers#electron-browser", "text": "Electron Browser", "level": 3 }, { "id": "app/references/launching-browsers#you-can-also-launch-electron-headed", "text": "You can also launch Electron headed:", "level": 4 }, { "id": "app/references/launching-browsers#chrome-browsers", "text": "Chrome Browsers", "level": 3 }, { "id": "app/references/launching-browsers#chrome-policy", "text": "Chrome policy", "level": 4 }, { "id": "app/references/launching-browsers#edge-browsers", "text": "Edge Browsers", "level": 3 }, { "id": "app/references/launching-browsers#edge-policy", "text": "Edge policy", "level": 4 }, { "id": "app/references/launching-browsers#firefox-browsers", "text": "Firefox Browsers", "level": 3 }, { "id": "app/references/launching-browsers#mozilla-geckodriver", "text": "Mozilla geckodriver", "level": 5 }, { "id": "app/references/launching-browsers#webkit-experimental", "text": "WebKit (Experimental)", "level": 3 }, { "id": "app/references/launching-browsers#linux-dependencies", "text": "Linux Dependencies", "level": 4 }, { "id": "app/references/launching-browsers#known-issues-with-experimentalwebkitsupport", "text": "Known Issues with experimentalWebKitSupport", "level": 4 }, { "id": "app/references/launching-browsers#launching-by-a-path", "text": "Launching by a path", "level": 3 }, { "id": "app/references/launching-browsers#customize-available-browsers", "text": "Customize available browsers", "level": 3 }, { "id": "app/references/launching-browsers#unsupported-browsers", "text": "Unsupported Browsers", "level": 3 }, { "id": "app/references/launching-browsers#browser-environment", "text": "Browser Environment", "level": 2 }, { "id": "app/references/launching-browsers#launching-browsers", "text": "Launching Browsers", "level": 3 }, { "id": "app/references/launching-browsers#cypress-profile", "text": "Cypress Profile", "level": 3 }, { "id": "app/references/launching-browsers#extra-tabs", "text": "Extra Tabs", "level": 3 }, { "id": "app/references/launching-browsers#disabled-barriers", "text": "Disabled Barriers", "level": 3 }, { "id": "app/references/launching-browsers#the-cypress-launched-browser-automatically", "text": "The Cypress launched browser automatically:", "level": 4 }, { "id": "app/references/launching-browsers#browser-icon", "text": "Browser Icon", "level": 2 }, { "id": "app/references/launching-browsers#troubleshooting", "text": "Troubleshooting", "level": 2 }, { "id": "app/references/launching-browsers#see-also", "text": "See also", "level": 2 } ] }, "chunks": [ { "id": "app/references/launching-browsers#what-youll-learn", "doc_id": "app/references/launching-browsers", "heading": "What you'll learn", "heading_level": 5, "content_markdown": "##### What you'll learn\n\n* How to launch browsers in Cypress\n* How to customize the list of available browsers\n* How to troubleshoot browser launching issues\n* Differences between Cypress browsers and regular browser environments\n\nWhen you run tests in Cypress, we launch a browser for you. This enables us to:\n\n1. Create a clean, pristine testing environment.\n2. Access the privileged browser APIs for automation.\n\nCypress currently supports Firefox and Chrome-family browsers (including Edge and Electron). To run tests optimally across these browsers in CI, check out the strategies demonstrated in the [cross browser Testing](/llm/markdown/app/guides/cross-browser-testing.md) guide.\n", "section": "app", "anchors": [ "what-youll-learn" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 131 }, { "id": "app/references/launching-browsers#browsers", "doc_id": "app/references/launching-browsers", "heading": "Browsers", "heading_level": 2, "content_markdown": "## Browsers\n\nWhen Cypress is initially launched, you can choose to test your application using number of browsers including:\n\n* [Chrome](https://www.google.com/chrome/)\n* [Chrome Beta](https://www.google.com/chrome/beta/)\n* [Chrome Canary](https://www.google.com/chrome/canary/)\n* [Chrome for Testing](https://github.com/GoogleChromeLabs/chrome-for-testing/)\n* [Chromium](https://www.chromium.org/Home)\n* [Edge](https://www.microsoft.com/edge)\n* [Edge Beta](https://www.microsoftedgeinsider.com/download)\n* [Edge Canary](https://www.microsoftedgeinsider.com/download)\n* [Edge Dev](https://www.microsoftedgeinsider.com/download)\n* [Electron](https://electron.atom.io/)\n* [Firefox](https://www.mozilla.org/firefox/)\n* [Firefox Developer Edition](https://www.mozilla.org/firefox/developer/)\n* [Firefox Nightly](https://www.mozilla.org/firefox/nightly/)\n* [WebKit (Experimental)](#WebKit-Experimental)\n\nCypress automatically detects available browsers on your OS. You can switch the browser by using the drop down near the top right corner:\n\n### Browser versions supported\n\nCypress officially supports the latest 3 major versions of Chrome, Firefox, and Edge. (For example, if the stable release of Chrome was 130, Cypress would officially support Chrome 128, 129, and 130.)\n\nSee each browser's official release schedule for more information.\n\n* [Chrome Release Schedule](https://chromiumdash.appspot.com/schedule)\n* [Firefox Release Schedule](https://whattrainisitnow.com/release/?version=release)\n* [Edge Release Schedule](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-release-schedule#microsoft-edge-releases)\n\n### Download specific Chrome version\n\nThe Chrome browser is evergreen - meaning it will automatically update itself, sometimes causing a breaking change in your automated tests. You can use the information in [Download Chromium](https://on.cypress.io/chromium-downloads) to download a specific released version of Chrome for Testing or Chromium for every platform.\n\n### Electron Browser\n\nIn addition to the browsers found on your system, you'll notice that Electron is an available browser. The Electron browser is a version of Chromium that comes with [Electron](https://electron.atom.io/).\n\nThe Electron browser has the advantage of coming baked into Cypress and does not need to be installed separately.\n\nBy default, when running [cypress run](/llm/markdown/app/references/command-line.md#cypress-run) from the CLI, we will launch all browsers headlessly.\n\n#### You can also launch Electron headed:\n\n```\ncypress run --headed\n```\n\nBecause Electron is the default browser - it is typically run in CI. If you are seeing failures in CI, to easily debug them you may want to run locally with the `--headed` option.\n\n### Chrome Browsers\n\nAll Chrome\\* flavored browsers are detected and supported by Cypress.\n\nYou can launch Chrome like this:\n\n```\ncypress run --browser chrome\n```\n\nTo use this command in CI, you need to install the browser you want - or use one of our [docker images](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images).\n\nBy default, we will launch Chrome headlessly during `cypress run`. To run Chrome headed, you can pass the `--headed` argument to `cypress run`.\n\nYou can also launch Chromium:\n\n```\ncypress run --browser chromium\n```\n\nOr Chrome Beta:\n\n```\ncypress run --browser chrome:beta\n```\n\nOr Chrome Canary:\n\n```\ncypress run --browser chrome:canary\n```\n\nOr Chrome for Testing:\n\n```\ncypress run --browser chrome-for-testing\n```\n\n#### Chrome policy\n\nIf Chrome policy is set, ensure that [RemoteDebuggingAllowed](https://chromeenterprise.google/policies/#RemoteDebuggingAllowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Chrome policy is generally applied to a Chrome-branded browser only, not to Chromium or Chrome for Testing browsers. Check by browsing to **chrome://policy**.\n\n### Edge Browsers\n\nMicrosoft Edge-family (Chromium-based) browsers are supported by Cypress.\n\nYou can launch Microsoft Edge like this:\n\n```\ncypress run --browser edge\n```\n\nOr Microsoft Edge Beta:\n\n```\ncypress run --browser edge:beta\n```\n\nOr Microsoft Edge Canary:\n\n```\ncypress run --browser edge:canary\n```\n\nOr Microsoft Edge Dev:\n\n```\ncypress run --browser edge:dev\n```\n\n#### Edge policy\n\nIf Edge policy is set, ensure that [RemoteDebuggingAllowed](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/remotedebuggingallowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Check by browsing to **edge://policy**.\n\n### Firefox Browsers\n\nFirefox-family browsers are supported by Cypress.\n\nYou can launch Firefox like this:\n\n```\ncypress run --browser firefox\n```\n\nOr Firefox Developer/Nightly Edition:\n\n```\ncypress run --browser firefox:devcypress run --browser firefox:nightly\n```\n\nTo use this command in CI, you need to install these other browsers - or use one of our [docker images](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images).\n\nBy default, we will launch Firefox headlessly during `cypress run`. To run Firefox headed, you can pass the `--headed` argument to `cypress run`.\n\n##### Mozilla geckodriver\n\nCypress requires the [Mozilla geckodriver](https://github.com/mozilla/geckodriver) to launch Firefox. To meet this requirement, the Cypress binary uses the separate npm wrapper package [geckodriver](https://github.com/webdriverio-community/node-geckodriver) to provide the Mozilla geckodriver. The wrapper downloads the latest driver version if it does not find any driver version cached locally.\n\nRetrieving the driver may fail if you are operating Cypress in an air-gapped environment without Internet connectivity and you do not have a cached driver version available.\n\nTo avoid this issue, use a current [Cypress Docker image](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images) `cypress/browsers` or `cypress/included`, built with Firefox 139, or above. These images include a Mozilla geckodriver version pre-installed. Using `cypress/factory:5.9.0`, or above, you can also build your own custom Cypress Docker image that includes a Mozilla geckodriver version. Refer to the `cypress/factory` [documentation](https://github.com/cypress-io/cypress-docker-images/blob/master/factory/README.md) for instructions on building custom images.\n\nIf you need to work without Docker, refer to the npm wrapper package geckodriver [documentation](https://github.com/webdriverio-community/node-geckodriver) for information about how to define a custom path for the driver or how to refer to a local CDN mirror site. Download the Mozilla geckodriver from the [releases](https://github.com/mozilla/geckodriver/releases) location.\n\n### WebKit (Experimental)\n\nCypress has [experimental](/llm/markdown/app/references/experiments.md) support for WebKit, Safari's browser engine. Testing your app with WebKit is representative of how your app would run in Safari. To opt-in to `experimentalWebKitSupport`, follow these steps:\n\n1. Add `experimentalWebKitSupport: true` to your [configuration](/llm/markdown/app/references/configuration.md) to enable the experiment.\n2. For installation on Linux, refer to [Linux Dependencies](#Linux-Dependencies) below.\n3. Install the `playwright-webkit` npm package in your repo to acquire WebKit itself:\n \n ```\n npm install playwright-webkit --save-dev\n ```\n \n4. Now, you should be able to use WebKit like any other browser. For example, to record with WebKit in CI:\n \n ```\n cypress run --browser webkit --record # ...\n ```\n \n\nWe built this experiment on top of the Playwright WebKit browser as a stepping stone towards creating a better UX with Cypress-provided browsers in the future. Thank you, Playwright contributors.\n\nWebKit support is _experimental_, so you may encounter issues. If you encounter an issue not on the \"Known Issues\" list, please [open an issue](https://github.com/cypress-io/cypress/issues/new/choose) on the GitHub repository.\n\n#### Linux Dependencies\n\nWebKit requires additional dependencies to run on Linux. To install the required dependencies, run this:\n\n```\nnpx playwright install-deps webkit\n```\n\n#### Known Issues with `experimentalWebKitSupport`\n\n* `cy.origin()` is not yet supported.\n* `cy.intercept()`'s `forceNetworkError` option is disabled.\n* When using `experimentalSingleTabRunMode` with video recording in WebKit, only the video for the first spec is recorded.\n* Some differences in `cy.type()` behavior:\n * `textInput` events are missing the `data` property\n * `beforeinput` events are missing the `inputType` property\n * `cy.type('{uparrow}')` and `cy.type('{downarrow}')` on an `input[type=number]` do not round to the nearest `step` specified\n* Stack traces may be missing some function names and location information.\n* See issues labeled [`experiment: webkit`](https://github.com/cypress-io/cypress/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22experiment%3A+webkit%22) for a complete list.\n\n### Launching by a path\n\nYou can launch any supported browser by specifying a path to the binary:\n\n```\ncypress run --browser /usr/bin/chromium\n```\n\n```\ncypress open --browser /usr/bin/chromium\n```\n\nCypress will automatically detect the type of browser supplied and launch it for you.\n\n[See the Command Line guide for more information about the `--browser` arguments](/llm/markdown/app/references/command-line.md#cypress-run-browser-lt-browser-name-or-path-gt)\n\n[Having trouble launching a browser? Check out our troubleshooting guide](/llm/markdown/app/references/troubleshooting.md#Launching-browsers)\n\n### Customize available browsers\n\nSometimes you might want to modify the list of browsers found before running tests.\n\nFor example, your web application might _only_ be designed to work in a Chrome browser, and not inside the Electron browser.\n\nIn the [setupNodeEvents](/llm/markdown/api/node-events/configuration-api.md) function, you can filter the list of browsers passed inside the `config` object and return the list of browsers you want available for selection during `cypress open`.\n\n* cypress.config.js\n* cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { // inside config.browsers array each object has information like // { // name: 'chrome', // channel: 'canary', // family: 'chromium', // displayName: 'Chrome Canary', // version: '133.0.6890.0', // path: // '/Applications/Google Chrome Canary.app/Contents/MacOS/Canary', // majorVersion: 133 // } return { browsers: config.browsers.filter( (b) => b.family === 'chromium' && b.name !== 'electron' ), } }, },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { // inside config.browsers array each object has information like // { // name: 'chrome', // channel: 'canary', // family: 'chromium', // displayName: 'Chrome Canary', // version: '133.0.6890.0', // path: // '/Applications/Google Chrome Canary.app/Contents/MacOS/Canary', // majorVersion: 133 // } return { browsers: config.browsers.filter( (b) => b.family === 'chromium' && b.name !== 'electron' ), } }, },})\n```\n\nWhen you open Cypress in a project that uses the above modifications to the `setupNodeEvents` function, Electron will no longer display in the list of available browsers.\n\nIf you return an empty list of browsers or `browsers: null`, the default list will be restored automatically.\n\nIf you have installed a Chromium-based browser like [Brave](https://brave.com/), [Vivaldi](https://vivaldi.com/) you can add them to the list of returned browsers. Here is a configuration that inserts a local Brave browser into the returned list.\n\n* cypress.config.js\n* cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const execa = require('execa')const findBrowser = () => { // the path is hard-coded for simplicity const browserPath = '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser' return execa(browserPath, ['--version']).then((result) => { // STDOUT will be like \"Brave Browser 77.0.69.135\" const [, version] = /Brave Browser (\\d+\\.\\d+\\.\\d+\\.\\d+)/.exec(result.stdout) const majorVersion = parseInt(version.split('.')[0]) return { name: 'Brave', channel: 'stable', family: 'chromium', displayName: 'Brave', version, path: browserPath, majorVersion, } })}module.exports = defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { return findBrowser().then((browser) => { return { browsers: config.browsers.concat(browser), } }) }, },})\n```\n\n```\nimport { defineConfig } from 'cypress'import execa from 'execa'const findBrowser = () => { // the path is hard-coded for simplicity const browserPath = '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser' return execa(browserPath, ['--version']).then((result) => { // STDOUT will be like \"Brave Browser 77.0.69.135\" const [, version] = /Brave Browser (\\d+\\.\\d+\\.\\d+\\.\\d+)/.exec(result.stdout) const majorVersion = parseInt(version.split('.')[0]) return { name: 'Brave', channel: 'stable', family: 'chromium', displayName: 'Brave', version, path: browserPath, majorVersion, } })}export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { return findBrowser().then((browser) => { return { browsers: config.browsers.concat(browser), } }) }, },})\n```\n\nOnce selected, the Brave browser is detected using the same approach as any other browser of the `chromium` family.\n\nIf you modify the list of browsers, you can see the [resolved configuration](/llm/markdown/app/references/configuration.md#Resolved-Configuration) in the **Settings** tab.\n\n### Unsupported Browsers\n\nSome browsers such as Internet Explorer are not currently supported.\n", "section": "app", "anchors": [ "browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 2320 }, { "id": "app/references/launching-browsers#browser-versions-supported", "doc_id": "app/references/launching-browsers", "heading": "Browser versions supported", "heading_level": 3, "content_markdown": "### Browser versions supported\n\nCypress officially supports the latest 3 major versions of Chrome, Firefox, and Edge. (For example, if the stable release of Chrome was 130, Cypress would officially support Chrome 128, 129, and 130.)\n\nSee each browser's official release schedule for more information.\n\n* [Chrome Release Schedule](https://chromiumdash.appspot.com/schedule)\n* [Firefox Release Schedule](https://whattrainisitnow.com/release/?version=release)\n* [Edge Release Schedule](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-release-schedule#microsoft-edge-releases)\n", "section": "app", "anchors": [ "browser-versions-supported" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 76 }, { "id": "app/references/launching-browsers#download-specific-chrome-version", "doc_id": "app/references/launching-browsers", "heading": "Download specific Chrome version", "heading_level": 3, "content_markdown": "### Download specific Chrome version\n\nThe Chrome browser is evergreen - meaning it will automatically update itself, sometimes causing a breaking change in your automated tests. You can use the information in [Download Chromium](https://on.cypress.io/chromium-downloads) to download a specific released version of Chrome for Testing or Chromium for every platform.\n", "section": "app", "anchors": [ "download-specific-chrome-version" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 65 }, { "id": "app/references/launching-browsers#electron-browser", "doc_id": "app/references/launching-browsers", "heading": "Electron Browser", "heading_level": 3, "content_markdown": "### Electron Browser\n\nIn addition to the browsers found on your system, you'll notice that Electron is an available browser. The Electron browser is a version of Chromium that comes with [Electron](https://electron.atom.io/).\n\nThe Electron browser has the advantage of coming baked into Cypress and does not need to be installed separately.\n\nBy default, when running [cypress run](/llm/markdown/app/references/command-line.md#cypress-run) from the CLI, we will launch all browsers headlessly.\n\n#### You can also launch Electron headed:\n\n```\ncypress run --headed\n```\n\nBecause Electron is the default browser - it is typically run in CI. If you are seeing failures in CI, to easily debug them you may want to run locally with the `--headed` option.\n", "section": "app", "anchors": [ "electron-browser" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 149 }, { "id": "app/references/launching-browsers#you-can-also-launch-electron-headed", "doc_id": "app/references/launching-browsers", "heading": "You can also launch Electron headed:", "heading_level": 4, "content_markdown": "#### You can also launch Electron headed:\n\n```\ncypress run --headed\n```\n\nBecause Electron is the default browser - it is typically run in CI. If you are seeing failures in CI, to easily debug them you may want to run locally with the `--headed` option.\n", "section": "app", "anchors": [ "you-can-also-launch-electron-headed" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 61 }, { "id": "app/references/launching-browsers#chrome-browsers", "doc_id": "app/references/launching-browsers", "heading": "Chrome Browsers", "heading_level": 3, "content_markdown": "### Chrome Browsers\n\nAll Chrome\\* flavored browsers are detected and supported by Cypress.\n\nYou can launch Chrome like this:\n\n```\ncypress run --browser chrome\n```\n\nTo use this command in CI, you need to install the browser you want - or use one of our [docker images](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images).\n\nBy default, we will launch Chrome headlessly during `cypress run`. To run Chrome headed, you can pass the `--headed` argument to `cypress run`.\n\nYou can also launch Chromium:\n\n```\ncypress run --browser chromium\n```\n\nOr Chrome Beta:\n\n```\ncypress run --browser chrome:beta\n```\n\nOr Chrome Canary:\n\n```\ncypress run --browser chrome:canary\n```\n\nOr Chrome for Testing:\n\n```\ncypress run --browser chrome-for-testing\n```\n\n#### Chrome policy\n\nIf Chrome policy is set, ensure that [RemoteDebuggingAllowed](https://chromeenterprise.google/policies/#RemoteDebuggingAllowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Chrome policy is generally applied to a Chrome-branded browser only, not to Chromium or Chrome for Testing browsers. Check by browsing to **chrome://policy**.\n", "section": "app", "anchors": [ "chrome-browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 227 }, { "id": "app/references/launching-browsers#chrome-policy", "doc_id": "app/references/launching-browsers", "heading": "Chrome policy", "heading_level": 4, "content_markdown": "#### Chrome policy\n\nIf Chrome policy is set, ensure that [RemoteDebuggingAllowed](https://chromeenterprise.google/policies/#RemoteDebuggingAllowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Chrome policy is generally applied to a Chrome-branded browser only, not to Chromium or Chrome for Testing browsers. Check by browsing to **chrome://policy**.\n", "section": "app", "anchors": [ "chrome-policy" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 81 }, { "id": "app/references/launching-browsers#edge-browsers", "doc_id": "app/references/launching-browsers", "heading": "Edge Browsers", "heading_level": 3, "content_markdown": "### Edge Browsers\n\nMicrosoft Edge-family (Chromium-based) browsers are supported by Cypress.\n\nYou can launch Microsoft Edge like this:\n\n```\ncypress run --browser edge\n```\n\nOr Microsoft Edge Beta:\n\n```\ncypress run --browser edge:beta\n```\n\nOr Microsoft Edge Canary:\n\n```\ncypress run --browser edge:canary\n```\n\nOr Microsoft Edge Dev:\n\n```\ncypress run --browser edge:dev\n```\n\n#### Edge policy\n\nIf Edge policy is set, ensure that [RemoteDebuggingAllowed](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/remotedebuggingallowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Check by browsing to **edge://policy**.\n", "section": "app", "anchors": [ "edge-browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 129 }, { "id": "app/references/launching-browsers#edge-policy", "doc_id": "app/references/launching-browsers", "heading": "Edge policy", "heading_level": 4, "content_markdown": "#### Edge policy\n\nIf Edge policy is set, ensure that [RemoteDebuggingAllowed](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-browser-policies/remotedebuggingallowed) is either undefined or set to `true`. If this is not the case, then Cypress will timeout, returning an `ECONNREFUSED` error, attempting to connect to the browser. Check by browsing to **edge://policy**.\n", "section": "app", "anchors": [ "edge-policy" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 57 }, { "id": "app/references/launching-browsers#firefox-browsers", "doc_id": "app/references/launching-browsers", "heading": "Firefox Browsers", "heading_level": 3, "content_markdown": "### Firefox Browsers\n\nFirefox-family browsers are supported by Cypress.\n\nYou can launch Firefox like this:\n\n```\ncypress run --browser firefox\n```\n\nOr Firefox Developer/Nightly Edition:\n\n```\ncypress run --browser firefox:devcypress run --browser firefox:nightly\n```\n\nTo use this command in CI, you need to install these other browsers - or use one of our [docker images](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images).\n\nBy default, we will launch Firefox headlessly during `cypress run`. To run Firefox headed, you can pass the `--headed` argument to `cypress run`.\n\n##### Mozilla geckodriver\n\nCypress requires the [Mozilla geckodriver](https://github.com/mozilla/geckodriver) to launch Firefox. To meet this requirement, the Cypress binary uses the separate npm wrapper package [geckodriver](https://github.com/webdriverio-community/node-geckodriver) to provide the Mozilla geckodriver. The wrapper downloads the latest driver version if it does not find any driver version cached locally.\n\nRetrieving the driver may fail if you are operating Cypress in an air-gapped environment without Internet connectivity and you do not have a cached driver version available.\n\nTo avoid this issue, use a current [Cypress Docker image](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images) `cypress/browsers` or `cypress/included`, built with Firefox 139, or above. These images include a Mozilla geckodriver version pre-installed. Using `cypress/factory:5.9.0`, or above, you can also build your own custom Cypress Docker image that includes a Mozilla geckodriver version. Refer to the `cypress/factory` [documentation](https://github.com/cypress-io/cypress-docker-images/blob/master/factory/README.md) for instructions on building custom images.\n\nIf you need to work without Docker, refer to the npm wrapper package geckodriver [documentation](https://github.com/webdriverio-community/node-geckodriver) for information about how to define a custom path for the driver or how to refer to a local CDN mirror site. Download the Mozilla geckodriver from the [releases](https://github.com/mozilla/geckodriver/releases) location.\n", "section": "app", "anchors": [ "firefox-browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 340 }, { "id": "app/references/launching-browsers#mozilla-geckodriver", "doc_id": "app/references/launching-browsers", "heading": "Mozilla geckodriver", "heading_level": 5, "content_markdown": "##### Mozilla geckodriver\n\nCypress requires the [Mozilla geckodriver](https://github.com/mozilla/geckodriver) to launch Firefox. To meet this requirement, the Cypress binary uses the separate npm wrapper package [geckodriver](https://github.com/webdriverio-community/node-geckodriver) to provide the Mozilla geckodriver. The wrapper downloads the latest driver version if it does not find any driver version cached locally.\n\nRetrieving the driver may fail if you are operating Cypress in an air-gapped environment without Internet connectivity and you do not have a cached driver version available.\n\nTo avoid this issue, use a current [Cypress Docker image](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images) `cypress/browsers` or `cypress/included`, built with Firefox 139, or above. These images include a Mozilla geckodriver version pre-installed. Using `cypress/factory:5.9.0`, or above, you can also build your own custom Cypress Docker image that includes a Mozilla geckodriver version. Refer to the `cypress/factory` [documentation](https://github.com/cypress-io/cypress-docker-images/blob/master/factory/README.md) for instructions on building custom images.\n\nIf you need to work without Docker, refer to the npm wrapper package geckodriver [documentation](https://github.com/webdriverio-community/node-geckodriver) for information about how to define a custom path for the driver or how to refer to a local CDN mirror site. Download the Mozilla geckodriver from the [releases](https://github.com/mozilla/geckodriver/releases) location.\n", "section": "app", "anchors": [ "mozilla-geckodriver" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 236 }, { "id": "app/references/launching-browsers#webkit-experimental", "doc_id": "app/references/launching-browsers", "heading": "WebKit (Experimental)", "heading_level": 3, "content_markdown": "### WebKit (Experimental)\n\nCypress has [experimental](/llm/markdown/app/references/experiments.md) support for WebKit, Safari's browser engine. Testing your app with WebKit is representative of how your app would run in Safari. To opt-in to `experimentalWebKitSupport`, follow these steps:\n\n1. Add `experimentalWebKitSupport: true` to your [configuration](/llm/markdown/app/references/configuration.md) to enable the experiment.\n2. For installation on Linux, refer to [Linux Dependencies](#Linux-Dependencies) below.\n3. Install the `playwright-webkit` npm package in your repo to acquire WebKit itself:\n \n ```\n npm install playwright-webkit --save-dev\n ```\n \n4. Now, you should be able to use WebKit like any other browser. For example, to record with WebKit in CI:\n \n ```\n cypress run --browser webkit --record # ...\n ```\n \n\nWe built this experiment on top of the Playwright WebKit browser as a stepping stone towards creating a better UX with Cypress-provided browsers in the future. Thank you, Playwright contributors.\n\nWebKit support is _experimental_, so you may encounter issues. If you encounter an issue not on the \"Known Issues\" list, please [open an issue](https://github.com/cypress-io/cypress/issues/new/choose) on the GitHub repository.\n\n#### Linux Dependencies\n\nWebKit requires additional dependencies to run on Linux. To install the required dependencies, run this:\n\n```\nnpx playwright install-deps webkit\n```\n\n#### Known Issues with `experimentalWebKitSupport`\n\n* `cy.origin()` is not yet supported.\n* `cy.intercept()`'s `forceNetworkError` option is disabled.\n* When using `experimentalSingleTabRunMode` with video recording in WebKit, only the video for the first spec is recorded.\n* Some differences in `cy.type()` behavior:\n * `textInput` events are missing the `data` property\n * `beforeinput` events are missing the `inputType` property\n * `cy.type('{uparrow}')` and `cy.type('{downarrow}')` on an `input[type=number]` do not round to the nearest `step` specified\n* Stack traces may be missing some function names and location information.\n* See issues labeled [`experiment: webkit`](https://github.com/cypress-io/cypress/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22experiment%3A+webkit%22) for a complete list.\n", "section": "app", "anchors": [ "webkit-experimental" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 373 }, { "id": "app/references/launching-browsers#known-issues-with-experimentalwebkitsupport", "doc_id": "app/references/launching-browsers", "heading": "Known Issues with experimentalWebKitSupport", "heading_level": 4, "content_markdown": "#### Known Issues with `experimentalWebKitSupport`\n\n* `cy.origin()` is not yet supported.\n* `cy.intercept()`'s `forceNetworkError` option is disabled.\n* When using `experimentalSingleTabRunMode` with video recording in WebKit, only the video for the first spec is recorded.\n* Some differences in `cy.type()` behavior:\n * `textInput` events are missing the `data` property\n * `beforeinput` events are missing the `inputType` property\n * `cy.type('{uparrow}')` and `cy.type('{downarrow}')` on an `input[type=number]` do not round to the nearest `step` specified\n* Stack traces may be missing some function names and location information.\n* See issues labeled [`experiment: webkit`](https://github.com/cypress-io/cypress/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22experiment%3A+webkit%22) for a complete list.\n", "section": "app", "anchors": [ "known-issues-with-experimentalwebkitsupport" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 125 }, { "id": "app/references/launching-browsers#launching-by-a-path", "doc_id": "app/references/launching-browsers", "heading": "Launching by a path", "heading_level": 3, "content_markdown": "### Launching by a path\n\nYou can launch any supported browser by specifying a path to the binary:\n\n```\ncypress run --browser /usr/bin/chromium\n```\n\n```\ncypress open --browser /usr/bin/chromium\n```\n\nCypress will automatically detect the type of browser supplied and launch it for you.\n\n[See the Command Line guide for more information about the `--browser` arguments](/llm/markdown/app/references/command-line.md#cypress-run-browser-lt-browser-name-or-path-gt)\n\n[Having trouble launching a browser? Check out our troubleshooting guide](/llm/markdown/app/references/troubleshooting.md#Launching-browsers)\n", "section": "app", "anchors": [ "launching-by-a-path" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 88 }, { "id": "app/references/launching-browsers#customize-available-browsers", "doc_id": "app/references/launching-browsers", "heading": "Customize available browsers", "heading_level": 3, "content_markdown": "### Customize available browsers\n\nSometimes you might want to modify the list of browsers found before running tests.\n\nFor example, your web application might _only_ be designed to work in a Chrome browser, and not inside the Electron browser.\n\nIn the [setupNodeEvents](/llm/markdown/api/node-events/configuration-api.md) function, you can filter the list of browsers passed inside the `config` object and return the list of browsers you want available for selection during `cypress open`.\n\n* cypress.config.js\n* cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')module.exports = defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { // inside config.browsers array each object has information like // { // name: 'chrome', // channel: 'canary', // family: 'chromium', // displayName: 'Chrome Canary', // version: '133.0.6890.0', // path: // '/Applications/Google Chrome Canary.app/Contents/MacOS/Canary', // majorVersion: 133 // } return { browsers: config.browsers.filter( (b) => b.family === 'chromium' && b.name !== 'electron' ), } }, },})\n```\n\n```\nimport { defineConfig } from 'cypress'export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { // inside config.browsers array each object has information like // { // name: 'chrome', // channel: 'canary', // family: 'chromium', // displayName: 'Chrome Canary', // version: '133.0.6890.0', // path: // '/Applications/Google Chrome Canary.app/Contents/MacOS/Canary', // majorVersion: 133 // } return { browsers: config.browsers.filter( (b) => b.family === 'chromium' && b.name !== 'electron' ), } }, },})\n```\n\nWhen you open Cypress in a project that uses the above modifications to the `setupNodeEvents` function, Electron will no longer display in the list of available browsers.\n\nIf you return an empty list of browsers or `browsers: null`, the default list will be restored automatically.\n\nIf you have installed a Chromium-based browser like [Brave](https://brave.com/), [Vivaldi](https://vivaldi.com/) you can add them to the list of returned browsers. Here is a configuration that inserts a local Brave browser into the returned list.\n\n* cypress.config.js\n* cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const execa = require('execa')const findBrowser = () => { // the path is hard-coded for simplicity const browserPath = '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser' return execa(browserPath, ['--version']).then((result) => { // STDOUT will be like \"Brave Browser 77.0.69.135\" const [, version] = /Brave Browser (\\d+\\.\\d+\\.\\d+\\.\\d+)/.exec(result.stdout) const majorVersion = parseInt(version.split('.')[0]) return { name: 'Brave', channel: 'stable', family: 'chromium', displayName: 'Brave', version, path: browserPath, majorVersion, } })}module.exports = defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { return findBrowser().then((browser) => { return { browsers: config.browsers.concat(browser), } }) }, },})\n```\n\n```\nimport { defineConfig } from 'cypress'import execa from 'execa'const findBrowser = () => { // the path is hard-coded for simplicity const browserPath = '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser' return execa(browserPath, ['--version']).then((result) => { // STDOUT will be like \"Brave Browser 77.0.69.135\" const [, version] = /Brave Browser (\\d+\\.\\d+\\.\\d+\\.\\d+)/.exec(result.stdout) const majorVersion = parseInt(version.split('.')[0]) return { name: 'Brave', channel: 'stable', family: 'chromium', displayName: 'Brave', version, path: browserPath, majorVersion, } })}export default defineConfig({ // setupNodeEvents can be defined in either // the e2e or component configuration e2e: { setupNodeEvents(on, config) { return findBrowser().then((browser) => { return { browsers: config.browsers.concat(browser), } }) }, },})\n```\n\nOnce selected, the Brave browser is detected using the same approach as any other browser of the `chromium` family.\n\nIf you modify the list of browsers, you can see the [resolved configuration](/llm/markdown/app/references/configuration.md#Resolved-Configuration) in the **Settings** tab.\n", "section": "app", "anchors": [ "customize-available-browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 747 }, { "id": "app/references/launching-browsers#browser-environment", "doc_id": "app/references/launching-browsers", "heading": "Browser Environment", "heading_level": 2, "content_markdown": "## Browser Environment\n\nCypress launches the browser in a way that's different from a regular browser environment. But it launches in a way that we believe makes testing _more reliable_ and _accessible_.\n\n### Launching Browsers\n\nWhen Cypress goes to launch your browser it will give you an opportunity to modify the arguments used to launch the browser.\n\nThis enables you to do things like:\n\n* Load your own extension\n* Enable or disable experimental features\n\n[This part of the API is documented here.](/llm/markdown/api/node-events/browser-launch-api.md)\n\n### Cypress Profile\n\nCypress generates its own isolated profile apart from your normal browser profile. This means things like `history` entries, `cookies`, and `3rd party extensions` from your regular browsing session will not affect your tests in Cypress.\n\n**Wait, I need my developer extensions!**\n\nThat's no problem - you have to reinstall them **once** in the Cypress launched browser. We'll continue to use this Cypress testing profile on subsequent launches so all of your configuration will be preserved.\n\n### Extra Tabs\n\nAny extra tabs (i.e. tabs other than the one opened by Cypress) will be closed between tests. We recommend using your own browser instead of the one launched by Cypress for general-purpose browsing.\n\n### Disabled Barriers\n\nCypress automatically disables certain functionality in the Cypress launched browser that tend to get in the way of automated testing.\n\n#### The Cypress launched browser automatically:\n\n* Ignores certificate errors.\n* Allows blocked pop-ups.\n* Disables 'Saving passwords'.\n* Disables 'Autofill forms and passwords'.\n* Disables asking to become your primary browser.\n* Disables device discovery notifications.\n* Disables language translations.\n* Disables restoring sessions.\n* Disables background network traffic.\n* Disables background and renderer throttling.\n* Disables prompts requesting permission to use devices like cameras or mics\n* Disables user gesture requirements for autoplaying videos.\n\nYou can see all of the default chrome command line switches we send [here](https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/browsers/chrome.ts#L36).\n", "section": "app", "anchors": [ "browser-environment" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 413 }, { "id": "app/references/launching-browsers#launching-browsers", "doc_id": "app/references/launching-browsers", "heading": "Launching Browsers", "heading_level": 3, "content_markdown": "### Launching Browsers\n\nWhen Cypress goes to launch your browser it will give you an opportunity to modify the arguments used to launch the browser.\n\nThis enables you to do things like:\n\n* Load your own extension\n* Enable or disable experimental features\n\n[This part of the API is documented here.](/llm/markdown/api/node-events/browser-launch-api.md)\n", "section": "app", "anchors": [ "launching-browsers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 68 }, { "id": "app/references/launching-browsers#cypress-profile", "doc_id": "app/references/launching-browsers", "heading": "Cypress Profile", "heading_level": 3, "content_markdown": "### Cypress Profile\n\nCypress generates its own isolated profile apart from your normal browser profile. This means things like `history` entries, `cookies`, and `3rd party extensions` from your regular browsing session will not affect your tests in Cypress.\n\n**Wait, I need my developer extensions!**\n\nThat's no problem - you have to reinstall them **once** in the Cypress launched browser. We'll continue to use this Cypress testing profile on subsequent launches so all of your configuration will be preserved.\n", "section": "app", "anchors": [ "cypress-profile" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 104 }, { "id": "app/references/launching-browsers#extra-tabs", "doc_id": "app/references/launching-browsers", "heading": "Extra Tabs", "heading_level": 3, "content_markdown": "### Extra Tabs\n\nAny extra tabs (i.e. tabs other than the one opened by Cypress) will be closed between tests. We recommend using your own browser instead of the one launched by Cypress for general-purpose browsing.\n", "section": "app", "anchors": [ "extra-tabs" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 48 }, { "id": "app/references/launching-browsers#disabled-barriers", "doc_id": "app/references/launching-browsers", "heading": "Disabled Barriers", "heading_level": 3, "content_markdown": "### Disabled Barriers\n\nCypress automatically disables certain functionality in the Cypress launched browser that tend to get in the way of automated testing.\n\n#### The Cypress launched browser automatically:\n\n* Ignores certificate errors.\n* Allows blocked pop-ups.\n* Disables 'Saving passwords'.\n* Disables 'Autofill forms and passwords'.\n* Disables asking to become your primary browser.\n* Disables device discovery notifications.\n* Disables language translations.\n* Disables restoring sessions.\n* Disables background network traffic.\n* Disables background and renderer throttling.\n* Disables prompts requesting permission to use devices like cameras or mics\n* Disables user gesture requirements for autoplaying videos.\n\nYou can see all of the default chrome command line switches we send [here](https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/browsers/chrome.ts#L36).\n", "section": "app", "anchors": [ "disabled-barriers" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 151 }, { "id": "app/references/launching-browsers#the-cypress-launched-browser-automatically", "doc_id": "app/references/launching-browsers", "heading": "The Cypress launched browser automatically:", "heading_level": 4, "content_markdown": "#### The Cypress launched browser automatically:\n\n* Ignores certificate errors.\n* Allows blocked pop-ups.\n* Disables 'Saving passwords'.\n* Disables 'Autofill forms and passwords'.\n* Disables asking to become your primary browser.\n* Disables device discovery notifications.\n* Disables language translations.\n* Disables restoring sessions.\n* Disables background network traffic.\n* Disables background and renderer throttling.\n* Disables prompts requesting permission to use devices like cameras or mics\n* Disables user gesture requirements for autoplaying videos.\n\nYou can see all of the default chrome command line switches we send [here](https://github.com/cypress-io/cypress/blob/develop/packages/server/lib/browsers/chrome.ts#L36).\n", "section": "app", "anchors": [ "the-cypress-launched-browser-automatically" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 120 }, { "id": "app/references/launching-browsers#browser-icon", "doc_id": "app/references/launching-browsers", "heading": "Browser Icon", "heading_level": 2, "content_markdown": "## Browser Icon\n\nYou might notice that if you already have the browser open you will see two of the same browser icons in your dock.\n\nWe understand that when Cypress is running in its own profile it can be difficult to tell the difference between your normal browser and Cypress.\n\nFor this reason you may find downloading and using a browser's release channel versions (Dev, Canary, etc) useful. These browsers have different icons from the standard stable browser, making them more distinguishable. You can also use the bundled [Electron browser](#Electron-Browser), which does not have a dock icon.\n\nAdditionally, in Chrome-based browsers, we've made the browser spawned by Cypress look different than regular sessions. You'll see a darker theme around the chrome of the browser. You'll always be able to visually distinguish these.\n", "section": "app", "anchors": [ "browser-icon" ], "path": "/llm/json/chunked/app/references/launching-browsers.json", "token_estimate": 177 } ] }