5.0.0 Release

source/_changelogs/5.0.0.md

@@ -0,0 +1,58 @@
+# 5.0.0
+
+*Released X/X/2020*
+
+**Summary:**
+
+Cypress now includes support for test retries! Similar to how Cypress will retry assertions when they fail, test retries will allow you to automatically retry a failed test prior to marking it as failed. Read our new guide on Test Retries for more details.
+
+**Breaking Changes:**
+
+**{% fa fa-exclamation-triangle red %} Please read our {% url "Migration Guide" migration-guide %} which explains the changes in more detail and how to change your code to migrate to Cypress 5.0.**
+
+- Test retries are on by default when running via {% url "`cypress run`" command-line#cypress-run %}. This means that tests will automatically be re-run up to 2 additional times (for a total of 3 attempts) before potentially being marked as a failed test. Additionally, the {% url "`cypress-plugin-retries`" https://github.com/Bkucera/cypress-plugin-retries %} plugin has been deprecated. Addresses {% issue 1313 %}.
+- The {% url "`Cypress.Cookies.defaults()`" cookies %} `whitelist` option has been renamed to `preserve` to more closely reflect its behavior.  Addressed in {% issue 7782 %}.
+- The `blacklistHosts` configuration has been renamed to {% url "`blockHosts`" configuration#Notes %} to more closely reflect its behavior. Addressed in {% issue 7622 %}.
+- The {% url "`cy.server()`" server %} `whitelist` option has been renamed to `ignore` to more closely reflect its behavior. Addresses {% issue 6642 %}.
+- `libgbm-dev` is now a requirement to run Cypress on Linux. Addressed in {% PR 7791 %}.
+- Values yielded by {% url "`cy.setCookie()`" setcookie %}, {% url "`cy.getCookie()`" getcookie %}, and {% url "`cy.getCookies()`" getcookies %} will now contain the `sameSite` property if specified. Addresses {% issue 6892 %}.
+- The `experimentalGetCookiesSameSite` configuration flag has been removed, since this behavior is now the default. Addresses {% issue 6892 %}.
+- The return type of the {% url "`Cypress.Blob`" blob %} methods `arrayBufferToBlob`, `base64StringToBlob`, `binaryStringToBlob`, and `dataURLToBlob` have changed from `Promise<Blob>` to `Blob`. Addresses {% issue 6001 %}.
+- We removed the default `esModuleInterop: true` option when using TypeScript so that it can now be overridden. Addresses {% issue 7575 %}.
+- Cypress now requires TypeScript 3.4+. Addressed in {% issue 7856 %}.
+- Installing Cypress on your system now requires Node.js 10+. Addresses {% issue 6574 %}.
+
+**Features:**
+
+- There's a new `retries` configuration option to configure the number of times to retry a failing test. Addresses {% issue 1313 %}.
+- You can now open a spec file directly from the **Tests** tab in the Test Runner by clicking the **Open in IDE** button. Addresses {% issue 7713 %}
+
+**Bugfixes:**
+
+- Cypress will now properly run on Firefox versions >= 75. Addressed in {% PR 7791 %}.
+- The Developer Tools menu will now always display in Electron when switching focus from Specs to the Test Runner. Addressed in {% PR 7791 %}.
+- We now emit the pass event from Mocha after all hooks have run. Fixes {% issue 7730 %}.
+- Debug logs from the `@benmalka/foxdriver` module will no longer appear if any `DEBUG` environment variable was set. Fixed {% issue 7723 %}.
+
+**Documentation Changes:**
+
+- We have a new guide on Test Retries.
+- Our {% url "Migration Guide" migration-guide %} has a new section for 5.0 migration.
+
+**Misc:**
+
+- The type for the `Window` object returned from {% url "`cy.window()`" window %} is now correct. Addresses {% issue 7856 %}.
+- The type definition for Cypress's `ApplicationWindow` can now be extended. Addresses {% issue 7856 %}.
+- We made some minor UI updates to the Test Runner. Addresses {% issue 7732 %}.
+
+**Dependency Updates**
+
+- Upgraded Chrome browser version used during cypress run and when selecting Electron browser in cypress open from `80` to `83`. Addressed in {% PR 7791 %}.
+- Upgraded bundled Node.js version from `12.8.1` to `12.14.1`. Addressed in {% PR 7791 %}.
+- Upgraded `electron` from `8.3.1` to `9.0.5`. Addressed in {% PR 7791 %}.
+- Upgraded `chalk` from `2.4.2` to `4.1.0`. Addressed in {% PR 7650 %}.
+- Upgraded `cli-table3` from `0.5.1` to `0.6.0`. Addressed in {% PR 7650 %}.
+- Upgraded `execa` from `1.0.0` to `4.0.2`. Addressed in {% PR 7650 %}.
+- Upgraded `log-symbols` from `3.0.0` to `4.0.0`. Addressed in {% PR 7650 %}.
+- Upgraded `tmp` from `0.1.0` to `0.2.1`. Addressed in {% PR 7650 %}.
+- Upgraded `fs-extra` from `8.1.0` to `9.0.1`. Addressed in {% PR 7650 %}.

source/_partial/linux_dependencies.md

@@ -1,13 +1,13 @@
 #### Ubuntu/Debian
 
 ```shell
-apt-get install libgtk2.0-0 libgtk-3-0 libnotify-dev libgconf-2-4 libnss3 libxss1
-libasound2 libxtst6 xauth xvfb
+apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4
+libnss3 libxss1 libasound2 libxtst6 xauth xvfb
 ```
 
 #### CentOS
 
 ```shell
-yum install -y xorg-x11-server-Xvfb gtk2-devel gtk3-devel libnotify-devel GConf2
-nss libXScrnSaver alsa-lib
+yum install -y xorg-x11-server-Xvfb gtk2-devel gtk3-devel libnotify-devel
+GConf2 nss libXScrnSaver alsa-lib
 ```

source/api/commands/getcookie.md

@@ -38,14 +38,14 @@ Option | Default | Description
 
 `cy.getCookie()` yields a cookie object with the following properties:
 
-- `name`
-- `value`
-- `path`
 - `domain`
+- `expiry` *(if specified)*
 - `httpOnly`
+- `name`
+- `path`
+- `sameSite` *(if specified)*
 - `secure`
-- `expiry`
-- `sameSite` *(will only be returned if the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`)*
+- `value`
 
 ### When a cookie matching the name could not be found:
 
@@ -140,7 +140,8 @@ When clicking on `getCookie` within the command log, the console outputs the fol
 {% imgTag /img/api/getcookie/inspect-cookie-object-properties-in-console.png "Console Log getcookie" %}
 
 {% history %}
-{% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`.
+{% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made `sameSite` property always available.
+{% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the `experimentalGetCookiesSameSite` configuration value is `true`.
 {% endhistory %}
 
 # See also

source/api/commands/getcookies.md

@@ -34,14 +34,14 @@ Option | Default | Description
 
 `cy.getCookies()` yields an array of cookie objects. Each cookie object has the following properties:
 
-- `name`
-- `value`
-- `path`
 - `domain`
+- `expiry` *(if specified)*
 - `httpOnly`
+- `name`
+- `path`
+- `sameSite` *(if specified)*
 - `secure`
-- `expiry`
-- `sameSite` *(will only be returned if the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`)*
+- `value`
 
 # Examples
 
@@ -98,6 +98,7 @@ When clicking on `getCookies` within the command log, the console outputs the fo
 {% imgTag /img/api/getcookies/test-application-cookies.png "Console Log getcookies" %}
 
 {% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made `sameSite` property always available.
 {% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`.
 {% endhistory %}
 

source/api/commands/server.md

@@ -57,7 +57,7 @@ Option | Default | Description
 `onAnyRequest` | `undefined` | callback function called when any request is sent
 `onAnyResponse` | `undefined` | callback function called when any response is returned
 `urlMatchingOptions` | `{ matchBase: true }` | The default options passed to `minimatch` when using glob strings to match URLs
-`whitelist` | function | Callback function that filters requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files.
+`ignore` | function | Callback function that filters requests from ever being logged or stubbed. By default this matches against asset-like requests such as for `.js`, `.jsx`, `.html`, and `.css` files.
 
 ## Yields {% helper_icon yields %}
 
@@ -70,7 +70,7 @@ Option | Default | Description
 ### After starting a server:
 
 - Any request that does **NOT** match a {% url `cy.route()` route %} will {% url 'pass through to the server' network-requests#Don’t-Stub-Responses %}.
-- Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is filtered and ignored.
+- Any request that matches the `options.ignore` function will **NOT** be logged or stubbed.
 - You will see requests named as `(XHR Stub)` or `(XHR)` in the Command Log.
 
 ```javascript
@@ -181,27 +181,27 @@ cy.server({
 
 ### Change the default filtering
 
-`cy.server()` comes with a `whitelist` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`.
+`cy.server()` comes with an `ignore` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`.
 
-Any request that passes the `whitelist` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific {% url `cy.route()` route %}).
+Any request that passes the `ignore` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific {% url `cy.route()` route %}).
 
 The idea is that we never want to interfere with static assets that are fetched via Ajax.
 
 **The default filter function in Cypress is:**
 
 ```javascript
-const whitelist = (xhr) => {
+const ignore = (xhr) => {
   // this function receives the xhr object in question and
-  // will filter if it's a GET that appears to be a static resource
-  return xhr.method === 'GET' && /\.(jsx?|html|css)(\?.*)?$/.test(xhr.url)
+  // will ignore if it's a GET that appears to be a static resource
+  return xhr.method === 'GET' && /\.(jsx?|coffee|html|less|s?css|svg)(\?.*)?$/.test(xhr.url)
 }
 ```
 
 **You can override this function with your own specific logic:**
 
 ```javascript
 cy.server({
-  whitelist: (xhr) => {
+  ignore: (xhr) => {
     // specify your own function that should return
     // truthy if you want this xhr to be ignored,
     // not logged, and not stubbed.
@@ -270,6 +270,7 @@ The intention of {% url "`cy.request()`" request %} is to be used for checking e
 - `cy.server()` does *not* log in the Command Log
 
 {% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Renamed `whitelist` option to `ignore`
 {% url "0.13.6" changelog#0-13-6 %} | Added `onAbort` callback option
 {% url "0.5.10" changelog#0-5-10 %} | Added `delay` option
 {% url "0.3.3" changelog#0-3-3 %} | Added `whitelist` option

source/api/commands/setcookie.md

@@ -46,16 +46,16 @@ Option | Default | Description
 
 ## Yields {% helper_icon yields %}
 
-`cy.setCookie()` yields a cookie object literal with the following properties:
+`cy.setCookie()` yields a cookie object with the following properties:
 
-- `name`
-- `value`
-- `path`
 - `domain`
+- `expiry` *(if specified)*
 - `httpOnly`
+- `name`
+- `path`
+- `sameSite` *(if specified)*
 - `secure`
-- `expiry`
-- `sameSite` *(will only be returned if the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`)*
+- `value`
 
 # Examples
 
@@ -100,6 +100,7 @@ When clicking on `setCookie` within the command log, the console outputs the fol
 {% imgTag /img/api/setcookie/see-cookie-properties-expiry-domain-and-others-in-test.png "Console Log setcookie" %}
 
 {% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made `sameSite` property always available.
 {% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`.
 {% url "0.16.0" changelog#0-16-0 %} | `cy.setCookie()` command added
 {% endhistory %}

source/api/cypress-api/cookies.md

@@ -129,7 +129,7 @@ Any change you make here will take effect immediately for the remainder of every
 A great place to put this configuration is in your `cypress/support/index.js` file, since it is loaded before any test files are evaluated.
 {% endnote %}
 
-### `whitelist` accepts:
+### `preserve` accepts:
 
 - String
 - Array
@@ -142,7 +142,7 @@ A great place to put this configuration is in your `cypress/support/index.js` fi
 // now any cookie with the name 'session_id' will
 // not be cleared before each test runs
 Cypress.Cookies.defaults({
-  whitelist: 'session_id'
+  preserve: 'session_id'
 })
 ```
 
@@ -152,7 +152,7 @@ Cypress.Cookies.defaults({
 // now any cookie with the name 'session_id' or 'remember_token'
 // will not be cleared before each test runs
 Cypress.Cookies.defaults({
-  whitelist: ['session_id', 'remember_token']
+  preserve: ['session_id', 'remember_token']
 })
 ```
 
@@ -162,15 +162,15 @@ Cypress.Cookies.defaults({
 // now any cookie that matches this RegExp
 // will not be cleared before each test runs
 Cypress.Cookies.defaults({
-  whitelist: /session|remember/
+  preserve: /session|remember/
 })
 ```
 
 ### Preserve Function
 
 ```javascript
 Cypress.Cookies.defaults({
-  whitelist: (cookie) => {
+  preserve: (cookie) => {
     // implement your own logic here
     // if the function returns truthy
     // then the cookie will not be cleared
@@ -180,6 +180,7 @@ Cypress.Cookies.defaults({
 ```
 
 {% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Renamed `whitelist` option to `preserve`
 {% url "0.16.1" changelog#0-16-1 %} | `{verbose: false}` option added
 {% url "0.16.0" changelog#0-16-0 %} | Removed support for `Cypress.Cookies.get`, `Cypress.Cookies.set` and `Cypress.Cookies.remove`
 {% url "0.12.4" changelog#0-12-4 %} | `Cypress.Cookies` API added

source/api/cypress-api/cypress-server.md

@@ -28,7 +28,7 @@ Pass in an options object to change the default behavior of `Cypress.Server`.
 Cypress.Server.defaults({
   delay: 500,
   force404: false,
-  whitelist: (xhr) => {
+  ignore: (xhr) => {
     // handle custom logic for filtering XHR requests
   }
 })

source/faq/questions/using-cypress-faq.md

@@ -420,7 +420,7 @@ You can preserve specific cookies across tests using the {% url "Cypress.Cookies
 // now any cookie with the name 'session_id' will
 // not be cleared before each test runs
 Cypress.Cookies.defaults({
-  whitelist: 'session_id'
+  preserve: 'session_id'
 })
 ```
 

source/guides/getting-started/installing-cypress.md

@@ -25,7 +25,7 @@ Cypress is a desktop application that is installed on your computer. The desktop
 
 If you're using `npm` to install Cypress, we support:
 
-- **Node.js** 8 and above
+- **Node.js** 10 and above
 
 ### Linux
 

source/guides/references/experiments.md

@@ -14,7 +14,6 @@ You can pass the {% url "configuration" configuration %} options below to enable
 
 Option | Default | Description
 ----- | ---- | ----
-`experimentalGetCookiesSameSite` | `false` | Adds `sameSite` values to the objects yielded from {% url "`cy.setCookie()`" setcookie %}, {% url "`cy.getCookie()`" getcookie %}, and {% url "`cy.getCookies()`" getcookies %}. This will become the default behavior in a later Cypress version.
 `experimentalComponentTesting` | `false` | Enables component testing using framework-specific adaptors. See {% urlHash "Component Testing" Component-Testing %} for more detail.
 `experimentalFetchPolyfill` | `false` | Automatically replaces `window.fetch` with a polyfill that Cypress can spy on and stub.
 `experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See {% issue 5273 %} for details.
@@ -126,6 +125,7 @@ cy.get('.container .my-button', { includeShadowDom: true })
 In the selector `.container .my-button`, the first part (`.container`) exists in the light DOM and the second part (`.my-button`) exists in the shadow DOM. This will not find the button element. Instead, you can use one of the methods in the above examples.
 
 {% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made it the default behavior.
 {% url "4.9.0" changelog#4-9-0 %} | Added support for `experimentalFetchPolyfill`.
 {% url "4.8.0" changelog#4-8-0 %} | Added support for `experimentalShadowDomSupport`.
 {% url "4.6.0" changelog#4-6-0 %} | Added support for `experimentalSourceRewriting`.