{"_id":"573d0ad1df206d0e00b9d3f4","project":"568fde81b700ce0d002f4b43","__v":0,"parentDoc":null,"user":"568fffce769f210d0013258f","category":{"_id":"5696c1168560a60d00e2c1d6","__v":9,"pages":["5696c11aaa12bc0d0050332c","5696c11aaa12bc0d0050332d","5696c11a8400d52d00dd5631","5696c11a59a6692d003fad06","56a007d14583912300b5efcf","56a007d166c8420d00d7fc7c","56a6824e683cfb0d00dc586f","56b383fe3ccec63700a7ac1c","56b3a7de0e4c450d00699d22"],"project":"568fde81b700ce0d002f4b43","version":"56954a94fe18811700c9bfda","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-01-13T21:26:46.069Z","from_sync":false,"order":5,"slug":"references","title":"References"},"version":{"_id":"56954a94fe18811700c9bfda","project":"568fde81b700ce0d002f4b43","__v":6,"createdAt":"2016-01-12T18:48:52.007Z","releaseDate":"2016-01-12T18:48:52.007Z","categories":["56954a95fe18811700c9bfdb","56954a95fe18811700c9bfdc","56954a95fe18811700c9bfdd","56954a95fe18811700c9bfde","56954a95fe18811700c9bfdf","56954a95fe18811700c9bfe0","56954a95fe18811700c9bfe1","56954a95fe18811700c9bfe2","56954a95fe18811700c9bfe3","56954a95fe18811700c9bfe4","5695649fdcaf0d1700cb8721","5696c1168560a60d00e2c1d6","56a7a32e79395317007c1ad6","5898fc3eec49fb0f004c2663","589cc675ea37da23004e05e1"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"foo","version_clean":"0.0.0","version":"0.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-19T00:37:37.467Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"# Contents\n\n- :fa-angle-right: [Managing Browsers](#section-managing-browsers)\n- :fa-angle-right: [Launching Browsers](#section-launching-browsers)\n  - [Electron Browser](#section-electron-browser)\n  - [Unsupported Browsers](#section-unsupported-browsers)\n- :fa-angle-right: [Clean Testing Environment](#section-clean-testing-environment)\n  - [Cypress Profile](#section-cypress-profile)\n  - [Testing Barriers](#section-removing-testing-barriers)\n  - [Tabbed Browsing](#section-tabbed-browsing)\n- :fa-angle-right: [Automation API's](#section-automation-apis)\n  - [Cypress Extension](#section-cypress-extension)\n  - [Browser Drivers](#section-browser-drivers)\n  - [No Selenium Server](#section-no-selenium-server)\n\n***\n\n# Managing Browsers\n\nWhen you're ready to start testing, Cypress launches the browser for you. It does this for two main reasons:\n\n1. To create a clean, pristine testing environment.\n2. To access the exclusive browser API's for automation.\n\n***\n\n# Launching Browsers\n\nWhen Cypress is initially [run from the Desktop application](https://on.cypress.io/guides/installing-and-running#section-running-tests-from-the-gui), you can choose to run Cypress in a select number of browsers including:\n\n- Chrome\n- Chromium\n- Canary\n\n![open browsers](https://cloud.githubusercontent.com/assets/1268976/15519992/11fa3c36-21d2-11e6-9557-9b0f4139ac70.gif)\n\nWe'll automatically detect available browsers based on your OS. In `Linux` we detect browsers by their executable binary, and in `OSX` we'll automatically find them even if they aren't in your `/Applications` folder.\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"I'm confused which is the Cypress browser and which is my own browser!\"\n}\n[/block]\n\nYou might notice that if you already have the browser open you will see two icons of the same browser in your Dock.\n\n![switching browsers](https://cloud.githubusercontent.com/assets/1268976/15520492/b812cfe6-21d4-11e6-8764-831f33bd0acf.gif)\n\nWe understand that when Cypress is running in its own profile it can be confusing telling the difference from your normal browser and Cypress. For this reason we recommend [downloading Chromium](https://download-chromium.appspot.com/) or [downloading Canary](https://www.google.com/chrome/browser/canary.html). These browsers both have different icons from the standard Chrome browser and it'll be much easier to tell the difference. You can also use the bundled [Electron browser](#section-electron-browser), which does not have a Dock icon.\n\n![switch canary](https://cloud.githubusercontent.com/assets/1268976/15520491/b812bfe2-21d4-11e6-99ea-c77dae947b26.gif)\n\nAdditionally, we've made the browsers 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\n![screen shot 2016-05-24 at 5 25 19 pm](https://cloud.githubusercontent.com/assets/1268976/15520464/936b3976-21d4-11e6-8aca-33d05f2c2a8b.png)\n\n***\n\n## Electron Browser\n\nIn addition to the browsers found on your system, you'll notice that `Electron` is another available browser (it may be the only browser if Cypress does not detect any compatible browsers on your system). The `Electron` browser is a version of Chrome that is bundled with [Electron](https://electron.atom.io/) (the platform underlying the Cypress app). Cypress uses it when running headless via `cypress run`. It may be useful for debugging issues that only occur when running headless.\n\nThe `Electron` browser does not have its own Dock icon or any chrome (address bar, tabs, bookmarks, etc).\n\n***\n\n## Unsupported Browsers\n\n![screen shot 2016-05-24 at 5 29 05 pm](https://cloud.githubusercontent.com/assets/1268976/15520572/12b158a0-21d5-11e6-92e0-2e75e42fa517.png)\n\n***\n\n# Clean Testing Environment\n\nWhen we launch browsers we open them in a way that makes testing more reliable and accessible. We do this in three ways:\n\n1. Creating an isolated testing profile\n2. Disabling virtually everything that gets in the way of testing\n3. Enabling access to browser automation API's\n\n***\n\n## Cypress Profile\n\nCypress generates its own isolated profile away from your regular browsing profile. This means things like `history` entries, `cookies`, and `3rd party extensions` from your regular browsing session will not affect Cypress.\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Wait, I need my developer extensions such as React Dev Tools, Batarang, or Ember Inspector!\"\n}\n[/block]\n\nThat's no problem - you simply have to reinstall them **once**. We'll continue to use this Cypress testing profile on subsequent launches so all of your configuration will automatically be preserved. Note that in the [Electron browser](#section-electron-browser), while it's possible to use the dev tools, it's not possible to install developer extensions.\n\n***\n\n## Testing Barriers\n\nCypress automatically disables certain functionality in your browser which can get in the way of automated testing.\n\nFor instance we will automatically:\n\n- Ignore certificate errors\n- Allow blocked pop-ups\n- Disable 'Saving passwords'\n- Disable 'Autofill forms and passwords'\n- Disable asking to become your primary browser\n- Disable language translations\n- Disable restoring sessions\n- Disable a ton of background network traffic\n- Disable background and renderer throttling\n\n***\n\n## Tabbed Browsing\n\n***\n\n# Automation API's\n\n## Cypress Extension\n<talk about not using the debugger protocol>\n\n***\n\n## Browser Drivers\n\n***\n\n## No Selenium Server","excerpt":"How and why Cypress manages your browser","slug":"browser-management","type":"basic","title":"Browser Management"}

Browser Management

How and why Cypress manages your browser

# Contents - :fa-angle-right: [Managing Browsers](#section-managing-browsers) - :fa-angle-right: [Launching Browsers](#section-launching-browsers) - [Electron Browser](#section-electron-browser) - [Unsupported Browsers](#section-unsupported-browsers) - :fa-angle-right: [Clean Testing Environment](#section-clean-testing-environment) - [Cypress Profile](#section-cypress-profile) - [Testing Barriers](#section-removing-testing-barriers) - [Tabbed Browsing](#section-tabbed-browsing) - :fa-angle-right: [Automation API's](#section-automation-apis) - [Cypress Extension](#section-cypress-extension) - [Browser Drivers](#section-browser-drivers) - [No Selenium Server](#section-no-selenium-server) *** # Managing Browsers When you're ready to start testing, Cypress launches the browser for you. It does this for two main reasons: 1. To create a clean, pristine testing environment. 2. To access the exclusive browser API's for automation. *** # Launching Browsers When Cypress is initially [run from the Desktop application](https://on.cypress.io/guides/installing-and-running#section-running-tests-from-the-gui), you can choose to run Cypress in a select number of browsers including: - Chrome - Chromium - Canary ![open browsers](https://cloud.githubusercontent.com/assets/1268976/15519992/11fa3c36-21d2-11e6-9557-9b0f4139ac70.gif) We'll automatically detect available browsers based on your OS. In `Linux` we detect browsers by their executable binary, and in `OSX` we'll automatically find them even if they aren't in your `/Applications` folder. [block:callout] { "type": "warning", "body": "I'm confused which is the Cypress browser and which is my own browser!" } [/block] You might notice that if you already have the browser open you will see two icons of the same browser in your Dock. ![switching browsers](https://cloud.githubusercontent.com/assets/1268976/15520492/b812cfe6-21d4-11e6-8764-831f33bd0acf.gif) We understand that when Cypress is running in its own profile it can be confusing telling the difference from your normal browser and Cypress. For this reason we recommend [downloading Chromium](https://download-chromium.appspot.com/) or [downloading Canary](https://www.google.com/chrome/browser/canary.html). These browsers both have different icons from the standard Chrome browser and it'll be much easier to tell the difference. You can also use the bundled [Electron browser](#section-electron-browser), which does not have a Dock icon. ![switch canary](https://cloud.githubusercontent.com/assets/1268976/15520491/b812bfe2-21d4-11e6-99ea-c77dae947b26.gif) Additionally, we've made the browsers 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. ![screen shot 2016-05-24 at 5 25 19 pm](https://cloud.githubusercontent.com/assets/1268976/15520464/936b3976-21d4-11e6-8aca-33d05f2c2a8b.png) *** ## Electron Browser In addition to the browsers found on your system, you'll notice that `Electron` is another available browser (it may be the only browser if Cypress does not detect any compatible browsers on your system). The `Electron` browser is a version of Chrome that is bundled with [Electron](https://electron.atom.io/) (the platform underlying the Cypress app). Cypress uses it when running headless via `cypress run`. It may be useful for debugging issues that only occur when running headless. The `Electron` browser does not have its own Dock icon or any chrome (address bar, tabs, bookmarks, etc). *** ## Unsupported Browsers ![screen shot 2016-05-24 at 5 29 05 pm](https://cloud.githubusercontent.com/assets/1268976/15520572/12b158a0-21d5-11e6-92e0-2e75e42fa517.png) *** # Clean Testing Environment When we launch browsers we open them in a way that makes testing more reliable and accessible. We do this in three ways: 1. Creating an isolated testing profile 2. Disabling virtually everything that gets in the way of testing 3. Enabling access to browser automation API's *** ## Cypress Profile Cypress generates its own isolated profile away from your regular browsing profile. This means things like `history` entries, `cookies`, and `3rd party extensions` from your regular browsing session will not affect Cypress. [block:callout] { "type": "warning", "body": "Wait, I need my developer extensions such as React Dev Tools, Batarang, or Ember Inspector!" } [/block] That's no problem - you simply have to reinstall them **once**. We'll continue to use this Cypress testing profile on subsequent launches so all of your configuration will automatically be preserved. Note that in the [Electron browser](#section-electron-browser), while it's possible to use the dev tools, it's not possible to install developer extensions. *** ## Testing Barriers Cypress automatically disables certain functionality in your browser which can get in the way of automated testing. For instance we will automatically: - Ignore certificate errors - Allow blocked pop-ups - Disable 'Saving passwords' - Disable 'Autofill forms and passwords' - Disable asking to become your primary browser - Disable language translations - Disable restoring sessions - Disable a ton of background network traffic - Disable background and renderer throttling *** ## Tabbed Browsing *** # Automation API's ## Cypress Extension <talk about not using the debugger protocol> *** ## Browser Drivers *** ## No Selenium Server