diff --git a/.textlintrc b/.textlintrc
index fcfa43610b..046d09c6fd 100644
--- a/.textlintrc
+++ b/.textlintrc
@@ -86,7 +86,7 @@
["craziest", "most complex"],
["dumb", "unintended"],
["insane", "outrageous"],
- ["blacklist", "blocklist"],
+ ["blacklist", "block"],
["whitelist", "allow"],
// Prefer American spelling
diff --git a/cypress.json b/cypress.json
index b3fcbecc93..e29e804841 100644
--- a/cypress.json
+++ b/cypress.json
@@ -2,5 +2,5 @@
"baseUrl": "http://localhost:2222",
"projectId": "ma3dkn",
"viewportWidth": 1500,
- "blacklistHosts": ["trackcmp.net", "js.hs-analytics.net", "js.hs-scripts.com"]
+ "blockHosts": ["trackcmp.net", "js.hs-analytics.net", "js.hs-scripts.com"]
}
diff --git a/gulpfile.js b/gulpfile.js
index afc3e846dc..427a2946ac 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -3,7 +3,7 @@ const RevAll = require('gulp-rev-all')
const clean = require('gulp-clean')
const revisionOpts = {
- dontGlobal: ['.ico', 'sitemap.xml', 'sitemap.xsl', 'logo.png', 'logo@2x.png'],
+ dontGlobal: ['.ico', 'sitemap.xml', 'sitemap.xsl', 'logo.png', 'logo@2x.png', '.mp4', '.woff', '.woff2', '.less'],
dontRenameFile: ['.html', 'CNAME'],
dontUpdateReference: ['.html'],
dontSearchFile: ['.js'],
diff --git a/lib/tags/usage.js b/lib/tags/usage.js
index e4f308d3ea..e7bd764eaa 100644
--- a/lib/tags/usage.js
+++ b/lib/tags/usage.js
@@ -45,6 +45,22 @@ module.exports = function usageOptions (hexo, args) {
withinSubject: () => {
return 'Element to search for children in. If null, search begins from root-level DOM element'
},
+
+ ctrlKey: () => {
+ return 'Activates the control key. Aliases: controlKey.'
+ },
+
+ altKey: () => {
+ return 'Activates the alt key (option key for Mac). Aliases: optionKey.'
+ },
+
+ shiftKey: () => {
+ return 'Activates the shift key.'
+ },
+
+ metaKey: () => {
+ return 'Activates the meta key (Windows key or command key for Mac). Aliases: commandKey, cmdKey.'
+ },
}
const blurb = blurbs[opt]
diff --git a/source/_changelogs/1.1.2.md b/source/_changelogs/1.1.2.md
index 3554edaa40..e4bbe49a24 100644
--- a/source/_changelogs/1.1.2.md
+++ b/source/_changelogs/1.1.2.md
@@ -11,9 +11,8 @@
- {% url 'Added ESLint, Docker, and TypeScript to Plugins' plugins %}
- {% url 'Added recipe for TypeScript with Browserify' recipes %}
-- {% url 'Added recipe for TypeScript with Webpack' recipes %}
+- {% url 'Added recipe for TypeScript with webpack' recipes %}
- {% url 'Added recipe for Direct Controlling AngularJS' recipes %}
- {% url 'Added recipe for E2E API Testing' recipes %}
- {% url 'Added more video tutorials' tutorials %}
- {% url 'Improved displaying list of Tutorials, Recipes, Applications, and Docker examples' recipes %}
-
diff --git a/source/_changelogs/5.0.0.md b/source/_changelogs/5.0.0.md
new file mode 100644
index 0000000000..25f02fc8f1
--- /dev/null
+++ b/source/_changelogs/5.0.0.md
@@ -0,0 +1,73 @@
+# 5.0.0
+
+*Released 8/19/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.**
+
+- The {% url "`cypress-plugin-retries`" https://github.com/Bkucera/cypress-plugin-retries %} plugin has been deprecated in favor of test retries built into Cypress. 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` to `Blob`. Addresses {% issue 6001 %}.
+- Cypress no longer supports file paths with a question mark `?` in them. We now use the {% url "webpack preprocessor" https://github.com/cypress-io/cypress-webpack-preprocessor %} by default and it does not support files with question marks. Addressed in {% PR 7982 %}.
+- For TypeScript compilation of spec, support, and plugins files, the `esModuleInterop` option is no longer coerced to `true`. If you need to utilize `esModuleInterop`, set it in your `tsconfig.json`. 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 %}.
+- In spec files, the values for the globals `__dirname` and `__filename` no longer include leading slashes. Addressed in {% PR 7982 %}.
+
+**Features:**
+
+- There's a new `retries` configuration option to configure the number of times to retry a failing test. Addresses {% issue 1313 %}.
+- {% url "`.click()`" click %}, {% url "`.dblclick()`" dblclick %}, and {% url "`.rightclick()`" rightclick %} now accept options `altKey`, `ctrlKey`, `metaKey`, and `shiftKey` to hold down key combinations while clicking. Addresses {% issue 486 %}.
+- You can now chain `.snapshot()` off of `cy.stub()` and `cy.spy()` to disabled snapshots during those commands. For example: `cy.stub().snapshot(false)`. Addresses {% issue 3849 %}.
+
+**Bugfixes:**
+
+- The error `Cannot set property 'err' of undefined` will no longer incorrectly throw when rerunning tests in the Test Runner. Fixes {% issue 7874 %} and {% issue 8193 %}.
+- Cypress will no longer throw a `Cannot read property 'isAttached' of undefined` error during `cypress run` on Firefox versions >= 75. Fixes {% PR 6813 %}.
+- The error `Maximum call stack size exceeded` will no longer throw when calling `scrollIntoView` on an element in the shadow dom. Fixes {% issue 7986 %}.
+- Cypress {% url "environment variables" environment-variables %} that accept arrays as their value will now properly evaluate as arrays. Fixes {% issue 6810 %}.
+- Elements having `display: inline` will no longer be considered hidden if it has child elements within it that are visible. Fixes {% issue 6183 %}.
+- When {% url "`experimentalShadowDomSupport`" experiments %} is enabled, {% url "`.parent()`" parent %} and {% url "`.parentsUntil()`" parentsuntil %} commands now work correctly in shadow dom as well as passing a selector to {% url "`.parents()`" parents %} when the subject is in the shadow dom. Fixed in {% PR 8202 %}.
+- Screenshots will now be correctly taken when a test fails in an `afterEach` or `beforeEach` hook after the hook has already passed. Fixes {% issue 3744 %}.
+- Cypress will no longer report screenshots overwritten in a `cy.screenshot()` {% url "`onAfterScreenshot`" screenshot#Get-screenshot-info-from-the-onAfterScreenshot-callback %} option as a unique screenshot. Fixes {% issue 8079 %}.
+- Taking screenshots will no longer fail when the screenshot names are too long for the filesystem to accept. Fixes {% issue 2403 %}.
+- The "last used browser" will now be correctly remembered during `cypress open` if a non-default-channel browser was selected. Fixes {% issue 8281 %}.
+- For TypeScript projects, `tsconfig.json` will now be loaded and used to configure TypeScript compilation of spec and support files. Fixes {% issue 7006 %} and {% issue 7503 %}.
+- `reporterStats` now correctly show the number of passed and failed tests when a test passes but the `afterEach` fails. Fixes {% issue 7730 %}.
+- The Developer Tools menu will now always display in Electron when switching focus from Specs to the Test Runner. Fixes {% PR 3559 %}.
+
+**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:**
+
+- Cypress now uses the {% url "webpack preprocessor" https://github.com/cypress-io/cypress-webpack-preprocessor %} by default to preprocess spec files.
+- The **Runs** tab within the Test Runner has a new improved design when the project has not been set up or login is required. Addressed in {% PR 8141 %}.
+- 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 %}.
+- The type definition for `reporterOptions` has been added. Addresses {% issue 7877 %}.
+
+**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 `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 `electron` from `8.3.1` to `9.2.0`. Addressed in {% PR 7791 %} and {% PR 8235 %}.
+- Upgraded `execa` from `1.0.0` to `4.0.2`. Addressed in {% PR 7650 %}.
+- Upgraded `express` from `4.16.4` to `4.17.1`. Addressed in {% PR 8179 %}.
+- Upgraded `fs-extra` from `8.1.0` to `9.0.1`. 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 %}.
diff --git a/source/_data/sidebar.yml b/source/_data/sidebar.yml
index eb90fbfff2..242ccf5288 100644
--- a/source/_data/sidebar.yml
+++ b/source/_data/sidebar.yml
@@ -28,6 +28,7 @@ guides:
module-api: module-api.html
debugging: debugging.html
network-requests: network-requests.html
+ test-retries: test-retries.html
continuous-integration: continuous-integration.html
parallelization: parallelization.html
environment-variables: environment-variables.html
diff --git a/source/_partial/allowed_test_config.md b/source/_partial/allowed_test_config.md
index 5c03389baf..d09e6758cb 100644
--- a/source/_partial/allowed_test_config.md
+++ b/source/_partial/allowed_test_config.md
@@ -8,6 +8,7 @@
- `env`
- `requestTimeout`
- `responseTimeout`
+- `retries`
- `viewportHeight`
- `viewportWidth`
- `waitForAnimations`
diff --git a/source/_partial/linux_dependencies.md b/source/_partial/linux_dependencies.md
index 23c1128592..109da35f29 100644
--- a/source/_partial/linux_dependencies.md
+++ b/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
```
diff --git a/source/api/commands/click.md b/source/api/commands/click.md
index 511c8a4514..c3dc21cf3e 100644
--- a/source/api/commands/click.md
+++ b/source/api/commands/click.md
@@ -54,9 +54,13 @@ Pass in an options object to change the default behavior of `.click()`.
Option | Default | Description
--- | --- | ---
+`altKey` | `false` | {% usage_options altKey %}
+`ctrlKey` | `false` | {% usage_options ctrlKey %}
`log` | `true` | {% usage_options log %}
`force` | `false` | {% usage_options force click %}
+`metaKey` | `false` | {% usage_options metaKey %}
`multiple` | `false` | {% usage_options multiple click %}
+`shiftKey` | `false` | {% usage_options shiftKey %}
`timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .click %}
## Yields {% helper_icon yields %}
@@ -124,27 +128,30 @@ By default, Cypress will error if you're trying to click multiple elements. By p
cy.get('[id^=btn]').click({ multiple: true })
```
-## Click with key combinations
+### Click with key combinations
-The `.click()` command may also be fired with key modifiers in combination with the {% url "`.type()`" type %} command in order to simulate character sequences while clicking, such as `ALT + click`. In order to keep the modifier key active, `{release: false}` should be passed to the options of the {% url "`.type()`" type %} command.
+The `.click()` command may also be fired with key modifiers in order to simulate holding key combinations while clicking, such as `ALT + click`.
-The following modifiers can be combined with `.click()`.
+{% note info %}
+You can also use key combinations during {% url "`.type()`" type %}. This offers options to hold down keys across multiple commands. See {% url "Key Combinations" type#Key-Combinations %} for more information.
+{% endnote %}
-Sequence | Notes
+The following keys can be combined with `.click()` through the `options`.
+
+Option | Notes
--- | ---
-`{alt}` | Activates the `altKey` modifier. Aliases: `{option}`
-`{ctrl}` | Activates the `ctrlKey` modifier. Aliases: `{control}`
-`{meta}` | Activates the `metaKey` modifier. Aliases: `{command}`, `{cmd}`
-`{shift}` | Activates the `shiftKey` modifier.
+`altKey` | {% usage_options altKey %}
+`ctrlKey` | {% usage_options ctrlKey %}
+`metaKey` | {% usage_options metaKey %}
+`shiftKey` | {% usage_options shiftKey %}
-### Shift click
+#### Shift click
```js
// execute a SHIFT + click on the first
-// { release: false } is necessary so that
-// SHIFT will not be released after the type command
-cy.get('body').type('{shift}', { release: false })
-cy.get('li:first').click()
+cy.get('li:first').click({
+ shiftKey: true
+})
```
# Notes
diff --git a/source/api/commands/dblclick.md b/source/api/commands/dblclick.md
index f91299f1ad..6c435862fc 100644
--- a/source/api/commands/dblclick.md
+++ b/source/api/commands/dblclick.md
@@ -54,9 +54,13 @@ Pass in an options object to change the default behavior of `.dblclick()`.
Option | Default | Description
--- | --- | ---
+`altKey` | `false` | {% usage_options altKey %}
+`ctrlKey` | `false` | {% usage_options ctrlKey %}
`log` | `true` | {% usage_options log %}
`force` | `false` | {% usage_options force dblclick %}
+`metaKey` | `false` | {% usage_options metaKey %}
`multiple` | `true` | {% usage_options multiple dblclick %}
+`shiftKey` | `false` | {% usage_options shiftKey %}
`timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .dblclick %}
## Yields {% helper_icon yields %}
@@ -125,27 +129,30 @@ You can turn this off by passing `multiple: false` to `.dblclick()`.
cy.get('button').dblclick({ multiple: false })
```
-## Double click with key combinations
+### Double click with key combinations
-The `.dblclick()` command may also be fired with key modifiers in combination with the {% url "`.type()`" type %} command in order to simulate character sequences while double clicking, such as `SHIFT + double click`. In order to keep the modifier key active, `{release: false}` should be passed to the options of the {% url "`.type()`" type %} command.
+The `.dblclick()` command may also be fired with key modifiers in order to simulate holding key combinations while double clicking, such as `SHIFT + double click`.
+
+{% note info %}
+You can also use key combinations during {% url "`.type()`" type %}. This offers options to hold down keys across multiple commands. See {% url "Key Combinations" type#Key-Combinations %} for more information.
+{% endnote %}
The following modifiers can be combined with `.dblclick()`.
-Sequence | Notes
+Option | Notes
--- | ---
-`{alt}` | Activates the `altKey` modifier. Aliases: `{option}`
-`{ctrl}` | Activates the `ctrlKey` modifier. Aliases: `{control}`
-`{meta}` | Activates the `metaKey` modifier. Aliases: `{command}`, `{cmd}`
-`{shift}` | Activates the `shiftKey` modifier.
+`altKey` | {% usage_options altKey %}
+`ctrlKey` | {% usage_options ctrlKey %}
+`metaKey` | {% usage_options metaKey %}
+`shiftKey` | {% usage_options shiftKey %}
-### Alt click
+#### Alt click
```js
-// execute a ALT + dblclick on the first
-// { release: false } is necessary so that
-// ALT will not be released after the type command
-cy.get('body').type('{alt}', { release: false })
-cy.get('li:first').dblclick()
+// execute ALT + dblclick on the first
+cy.get('li:first').dblclick({
+ altKey: true
+})
```
# Notes
diff --git a/source/api/commands/getcookie.md b/source/api/commands/getcookie.md
index b6b6d6f1cc..557f87ab60 100644
--- a/source/api/commands/getcookie.md
+++ b/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
diff --git a/source/api/commands/getcookies.md b/source/api/commands/getcookies.md
index 9f32614dc0..2277021c22 100644
--- a/source/api/commands/getcookies.md
+++ b/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 %}
diff --git a/source/api/commands/rightclick.md b/source/api/commands/rightclick.md
index b0b5d58455..64a31b7079 100644
--- a/source/api/commands/rightclick.md
+++ b/source/api/commands/rightclick.md
@@ -58,9 +58,13 @@ Pass in an options object to change the default behavior of `.rightclick()`.
Option | Default | Description
--- | --- | ---
+`altKey` | `false` | {% usage_options altKey %}
+`ctrlKey` | `false` | {% usage_options ctrlKey %}
`log` | `true` | {% usage_options log %}
`force` | `false` | {% usage_options force rightclick %}
+`metaKey` | `false` | {% usage_options metaKey %}
`multiple` | `false` | {% usage_options multiple rightclick %}
+`shiftKey` | `false` | {% usage_options shiftKey %}
`timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .rightclick %}
## Yields {% helper_icon yields %}
@@ -127,27 +131,30 @@ By default, Cypress will error if you're trying to right click multiple elements
cy.get('.open-menu').rightclick({ multiple: true })
```
-## Right click with key combinations
+### Right click with key combinations
-The `.rightclick()` command may also be fired with key modifiers in combination with the {% url "`.type()`" type %} command in order to simulate character sequences while right clicking, such as `ALT + rightclick`. In order to keep the modifier key active, `{release: false}` should be passed to the options of the {% url "`.type()`" type %} command.
+The `.rightclick()` command may also be fired with key modifiers in order to simulate holding key combinations while right clicking, such as `ALT + rightclick`.
-The following modifiers can be combined with `.rightclick()`.
+{% note info %}
+You can also use key combinations during {% url "`.type()`" type %}. This offers options to hold down keys across multiple commands. See {% url "Key Combinations" type#Key-Combinations %} for more information.
+{% endnote %}
+
+The following key can be combined with `.rightclick()` through the `options`..
-Sequence | Notes
+Option | Notes
--- | ---
-`{alt}` | Activates the `altKey` modifier. Aliases: `{option}`
-`{ctrl}` | Activates the `ctrlKey` modifier. Aliases: `{control}`
-`{meta}` | Activates the `metaKey` modifier. Aliases: `{command}`, `{cmd}`
-`{shift}` | Activates the `shiftKey` modifier.
+`altKey` | {% usage_options altKey %}
+`ctrlKey` | {% usage_options ctrlKey %}
+`metaKey` | {% usage_options metaKey %}
+`shiftKey` | {% usage_options shiftKey %}
-### Command right click
+#### Command right click
```js
// execute a CMD + right click on the .menu-item
-// { release: false } is necessary so that
-// CMD will not be released after the type command
-cy.get('body').type('{cmd}', { release: false })
-cy.get('.menu-item').rightclick()
+cy.get('.menu-item').rightclick({
+ metaKey: true
+})
```
# Notes
diff --git a/source/api/commands/server.md b/source/api/commands/server.md
index 2693fbc78c..e039e7ce09 100644
--- a/source/api/commands/server.md
+++ b/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#Use-Server-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,19 +181,19 @@ 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)
}
```
@@ -201,7 +201,7 @@ const whitelist = (xhr) => {
```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
diff --git a/source/api/commands/setcookie.md b/source/api/commands/setcookie.md
index 411edaab7c..7394f4b1f9 100644
--- a/source/api/commands/setcookie.md
+++ b/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 %}
diff --git a/source/api/commands/type.md b/source/api/commands/type.md
index 9547ae132f..f86b214ffe 100644
--- a/source/api/commands/type.md
+++ b/source/api/commands/type.md
@@ -185,6 +185,10 @@ Special characters (`{leftarrow}`, `{selectall}`, etc.) are not permitted.
When using special character sequences, it's possible to activate modifier keys and type key combinations, such as `CTRL + R` or `SHIFT + ALT + Q`. The modifier(s) remain activated for the duration of the `.type()` command, and are released when all subsequent characters are typed, unless {% url '`{release: false}`' type#Options %} is passed as an {% url 'option' type#Key-Combinations %}. A `keydown` event is fired when a modifier is activated and a `keyup` event is fired when it is released.
+{% note info %}
+You can also use key combinations during {% url "`.click()`" click#Click-with-key-combinations %}, {% url "`.rightclick()`" rightclick#Right-click-with-key-combinations %} and {% url "`.dblclick()`" dblclick#Double-click-with-key-combinations %} through their options. See each doc for more information.
+{% endnote %}
+
### Type a key combination
```javascript
diff --git a/source/api/cypress-api/cookies.md b/source/api/cypress-api/cookies.md
index e0257e5171..163b57f858 100644
--- a/source/api/cypress-api/cookies.md
+++ b/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,7 +162,7 @@ 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/
})
```
@@ -170,7 +170,7 @@ Cypress.Cookies.defaults({
```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
diff --git a/source/api/cypress-api/cypress-server.md b/source/api/cypress-api/cypress-server.md
index 5052eca7cf..1a1329a1aa 100644
--- a/source/api/cypress-api/cypress-server.md
+++ b/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
}
})
diff --git a/source/api/plugins/preprocessors-api.md b/source/api/plugins/preprocessors-api.md
index 56be113d75..f80b180890 100644
--- a/source/api/plugins/preprocessors-api.md
+++ b/source/api/plugins/preprocessors-api.md
@@ -14,34 +14,33 @@ We've created three preprocessors as examples for you to look at. These are full
The code contains comments that explain how it utilizes the preprocessor API.
-* {% url 'Browserify Preprocessor' https://github.com/cypress-io/cypress-browserify-preprocessor %}
-* {% url 'webpack Preprocessor' https://github.com/cypress-io/cypress-webpack-preprocessor %}
-* {% url 'Watch Preprocessor' https://github.com/cypress-io/cypress-watch-preprocessor %}
+* {% url 'webpack preprocessor' https://github.com/cypress-io/cypress-webpack-preprocessor %}
+* {% url 'Browserify preprocessor' https://github.com/cypress-io/cypress-browserify-preprocessor %}
+* {% url 'Watch preprocessor' https://github.com/cypress-io/cypress-watch-preprocessor %}
# Defaults
-By default, Cypress comes packaged with the **Browserify Preprocessor** already installed.
+By default, Cypress comes packaged with the **webpack preprocessor** already installed.
-The Browserify Preprocessor handles:
+The webpack preprocessor handles:
+- ES2015 and JSX via Babel
+- TypeScript
- CoffeeScript `1.x.x`
-- ES2015 via Babel
-- JSX and CJSX
- Watching and caching files
-The exact default configuration options {% url 'can be found here' https://github.com/cypress-io/cypress-browserify-preprocessor#browserifyoptions %}.
-
{% note info %}
-Are you looking to change the **default options** for Browserify?
+Are you looking to change the **default options** for webpack?
{% endnote %}
-Changing the Browserify options lets you:
+If you already use webpack in your project, you can pass in your webpack config as {% url 'shown here' https://github.com/cypress-io/cypress-webpack-preprocessor#options %}.
+
+If you don't use webpack in your project or would like to keep the majority of the default options, you can {% url 'modify the default options' https://github.com/cypress-io/cypress-webpack-preprocessor#modifying-default-options %}. Editing the options allows you to do things like:
- Add your own Babel plugins
+- Modify options for TypeScript compilation
- Add support for CoffeeScript `2.x.x`
-Please read this link in the {% url 'Browserify preprocessor' https://github.com/cypress-io/cypress-browserify-preprocessor#modifying-default-options %} repo for instructions on modifying these.
-
# Usage
To use a preprocessor, you should bind to the `file:preprocessor` event in your {% url "`pluginsFile`" configuration#Folders-Files %}:
diff --git a/source/api/utilities/blob.md b/source/api/utilities/blob.md
index ddc6b123fa..1f3b5502d5 100644
--- a/source/api/utilities/blob.md
+++ b/source/api/utilities/blob.md
@@ -30,26 +30,26 @@ cy.Blob.method() // Errors, cannot be chained off 'cy'
## Image Fixture
-**Using an image fixture**
+### Using an image fixture for jQuery plugin upload
```javascript
// programmatically upload the logo
cy.fixture('images/logo.png').as('logo')
cy.get('input[type=file]').then(function($input) {
// convert the logo base64 string to a blob
- return Cypress.Blob.base64StringToBlob(this.logo, 'image/png')
- .then((blob) => {
- // pass the blob to the fileupload jQuery plugin
- // used in your application's code
- // which initiates a programmatic upload
- $input.fileupload('add', { files: blob })
- })
+ const blob = Cypress.Blob.base64StringToBlob(this.logo, 'image/png')
+
+ // pass the blob to the fileupload jQuery plugin
+ // https://github.com/blueimp/jQuery-File-Upload
+ // used in your application's code
+ // which initiates a programmatic upload
+ $input.fileupload('add', { files: blob })
})
```
## Getting dataUrl string
-**Create an `img` element and set its `src` to the `dataUrl`**
+### Create an `img` element and set its `src` to the `dataUrl`
```javascript
return Cypress.Blob.imgSrcToDataURL('/assets/img/logo.png').then((dataUrl) => {
@@ -63,6 +63,11 @@ return Cypress.Blob.imgSrcToDataURL('/assets/img/logo.png').then((dataUrl) => {
})
```
+{% history %}
+{% url "5.0.0" changelog %} | Return type of `arrayBufferToBlob`, `base64StringToBlob`, `binaryStringToBlob`, and `dataURLToBlob` methods changed from `Promise` to `Blob`
+{% url "5.0.0" changelog %} | Added `arrayBufferToBinaryString`, `binaryStringToArrayBuffer` methods.
+{% endhistory %}
+
# See also
-- {% url 'Bundled Tools' bundled-tools %}
\ No newline at end of file
+- {% url 'Bundled Tools' bundled-tools %}
diff --git a/source/faq/questions/using-cypress-faq.md b/source/faq/questions/using-cypress-faq.md
index 7689d399ee..4671a3cac0 100644
--- a/source/faq/questions/using-cypress-faq.md
+++ b/source/faq/questions/using-cypress-faq.md
@@ -281,7 +281,7 @@ Yes. {% url "You can override this with `userAgent` in your configuration file (
## {% fa fa-angle-right %} Can I block traffic going to specific domains? I want to block Google Analytics or other providers.
-Yes. {% url "You can set this with `blacklistHosts` in your configuration file (`cypress.json` by default)." configuration#Browser %}
+Yes. {% url "You can set this with `blockHosts` in your configuration file (`cypress.json` by default)." configuration#Browser %}
Also, check out our {% url 'Stubbing Google Analytics Recipe' recipes#Stubbing-and-spying %}.
@@ -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'
})
```
@@ -484,7 +484,7 @@ describe('Logo', () => {
The code you write in Cypress is executed in the browser, so you can import or require JS modules, *but* only those that work in a browser.
-You can `require` or `import` them as you're accustomed to. We preprocess your spec files with `babel` and `browserify`.
+You can `require` or `import` them as you're accustomed to. We preprocess your spec files with webpack and Babel.
We recommend utilizing one of the following to execute code outside of the browser. Furthermore, you can use your own Node version during code excecution by setting the {% url "`nodeVersion`" configuration#Node-version %} in your configuration.
@@ -545,7 +545,7 @@ Not at the moment. {% issue 587 "There is an open issue for this." %}
Yes. You can customize how specs are processed by using one of our {% url 'preprocessor plugins' plugins %} or by {% url 'writing your own custom preprocessor' preprocessors-api %}.
-Typically you'd reuse your existing `babel` and `webpack` configurations.
+Typically you'd reuse your existing Babel and webpack configurations.
## {% fa fa-angle-right %} How does one determine what the latest version of Cypress is?
@@ -628,7 +628,7 @@ Also, check out our {% url 'Stubbing `console` Receipe' recipes#Stubbing-and-spy
## {% fa fa-angle-right %} How do I use special characters with `cy.get()`?
-Special characters like `/`, `.` are valid characters for ids {% url "according to the CSS spec" https://www.w3.org/TR/html50/dom.html#the-id-attribute %}.
+Special characters like `/`, `.` are valid characters for ids {% url "according to the CSS spec" https://www.w3.org/TR/html50/dom.html#the-id-attribute %}.
To test elements with those characters in ids, they need to be escaped with {% url "`CSS.escape`" https://developer.mozilla.org/en-US/docs/Web/API/CSS/escape %} or {% url "`Cypress.$.escapeSelector`" https://api.jquery.com/jQuery.escapeSelector/ %}.
diff --git a/source/guides/core-concepts/retry-ability.md b/source/guides/core-concepts/retry-ability.md
index e55905a794..64c3ab155d 100644
--- a/source/guides/core-concepts/retry-ability.md
+++ b/source/guides/core-concepts/retry-ability.md
@@ -12,6 +12,10 @@ title: Retry-ability
A core feature of Cypress that assists with testing dynamic web applications is retry-ability. Like a good transmission in a car, it usually works without you noticing it. But understanding how it works will help you write faster tests with fewer run-time surprises.
+{% note info "Test Retries" %}
+If you are looking to retry tests a configured number of times when the test fails, check out our official guide on {% url "Test Retries" test-retries %}.
+{% endnote %}
+
# Commands vs assertions
There are two types of methods you can call in your Cypress tests: **commands** and **assertions**. For example, there are 6 commands and 2 assertions in the test below.
@@ -436,3 +440,4 @@ Watch the short video below to see this example in action
- You can add retry-ability to your own {% url "custom commands" custom-commands %}; see {% url 'this pull request to cypress-xpath' https://github.com/cypress-io/cypress-xpath/pull/12/files %} for an example.
- You can retry any function with attached assertions using this 3rd party plugin {% url cypress-pipe https://github.com/NicholasBoll/cypress-pipe %}.
- See retry-ability examples in the {% url "Cypress should callback" https://glebbahmutov.com/blog/cypress-should-callback/ %} blog post.
+- To learn how to enable Cypress' test retries functionality, which retries tests that fail up to the configured number, check out our official guide on {% url "Test Retries" test-retries %}.
diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md
index b83b4480cb..444bb4214b 100644
--- a/source/guides/core-concepts/writing-and-organizing-tests.md
+++ b/source/guides/core-concepts/writing-and-organizing-tests.md
@@ -331,33 +331,39 @@ specify(name, config, fn)
{% partial allowed_test_config %}
-### Suite of test configuration
+### Suite configuration
-You can configure the size of the viewport height and width within a suite.
+If you want to target a suite of tests to run or be excluded when run in a specific browser, you can override the `browser` configuration within the suite configuration. The `browser` option accepts the same arguments as {% url "`Cypress.isBrowser()`" isbrowser %}.
```js
-describe('page display on medium size screen', {
- viewportHeight: 1000,
- viewportWidth: 400
-}, () => {
- it('does not display sidebar', () => {
- cy.get('#sidebar').should('not.be.visible')
+describe('When in Chrome', { browser: '!chrome' } () => {
+ it('Shows warning', () => {
+ cy.get('.browser-warning')
+ .should('contain', 'For optimal viewing, use Chrome browser')
})
- it('shows hamburger menu', () => {
- cy.get('#header').find('i.menu').should('be.visible')
+ it('Links to browser compatibility doc', () => {
+ cy.get('a.browser-compat')
+ .should('have.attr', 'href')
+ .and('include', 'browser-compatibility)
})
})
```
### Single test configuration
-If you want to target a test to run or be excluded when run in a specific browser, you can override the `browser` configuration within the test configuration. The `browser` option accepts the same arguments as {% url "`Cypress.isBrowser()`" isbrowser %}.
+You can configure the number of retry attempts during `cypress run` or `cypress open`. See {% url "Test Retries" test-retries %} for more information.
```js
-it('Show warning outside Chrome', { browser: '!chrome' }, () => {
- cy.get('.browser-warning')
- .should('contain', 'For optimal viewing, use Chrome browser')
+it('should redirect unauthenticated user to sign-in page', {
+ retries: {
+ runMode: 3,
+ openMode: 2
+ }
+ } () => {
+ cy.visit('/')
+ // ...
+ })
})
```
@@ -485,7 +491,7 @@ Set the {% url `watchForFileChanges` configuration#Global %} configuration prope
The `watchForFileChanges` property is only in effect when running Cypress using {% url "`cypress open`" command-line#cypress-open %}.
{% endnote %}
-The component responsible for the file-watching behavior in Cypress is the {% url 'Cypress Browserify Preprocessor' https://github.com/cypress-io/cypress-browserify-preprocessor %}. This is the default file-watcher packaged with Cypress.
+The component responsible for the file-watching behavior in Cypress is the {% url '`cypress-webpack-preprocessor`' https://github.com/cypress-io/cypress-webpack-preprocessor %}. This is the default file-watcher packaged with Cypress.
If you need further control of the file-watching behavior you can configure this preprocessor explicitly: it exposes options that allow you to configure behavior such as _what_ is watched and the delay before emitting an "update" event after a change.
diff --git a/source/guides/getting-started/installing-cypress.md b/source/guides/getting-started/installing-cypress.md
index c4d1b3a7f1..bdce8ea63f 100644
--- a/source/guides/getting-started/installing-cypress.md
+++ b/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
diff --git a/source/guides/guides/module-api.md b/source/guides/guides/module-api.md
index 843245409e..93b0b96eff 100644
--- a/source/guides/guides/module-api.md
+++ b/source/guides/guides/module-api.md
@@ -87,14 +87,52 @@ cypress.run({
"osVersion": "14.5.0",
"runs": [{
"error": null,
- "hooks": [...],
+ "hooks": [{
+ "hookName": "before each",
+ "title": [ "before each hook" ],
+ "body": "function () {\n expect(true).to.be["true"];\n}"
+ }],
"reporter": "spec",
"reporterStats": {...},
- "screenshots": [],
"shouldUploadVideo": true,
"spec": {...},
- "stats": {...},
- "tests": [...],
+ "stats": {
+ "suites": 1,
+ "tests": 1,
+ "passes": 0,
+ "pending": 0,
+ "skipped": 0,
+ "failures": 1,
+ "startedAt": "2020-08-05T08:38:37.589Z",
+ "endedAt": "2018-07-11T17:53:35.675Z",
+ "duration": 1171
+ },
+ "tests": [{
+ "title": [ "test" ],
+ "state": "failed",
+ "body": "function () {\n expect(true).to.be["false"];\n}",
+ "displayError": "AssertionError: expected true to be false\n' +
+ ' at Context.eval (...cypress/integration/spec.js:5:21",
+ "attempts": [{
+ "state": "failed",
+ "error": {
+ "message": "expected true to be false",
+ "name": "AssertionError",
+ "stack": "AssertionError: expected true to be false\n' +
+ ' at Context.eval (...cypress/integration/spec.js:5:21"
+ },
+ "screenshots": [{
+ "name": null,
+ "takenAt": "2020-08-05T08:52:20.432Z",
+ "path": "User/janelane/my-app/cypress/screenshots/spec.js/test (failed).png",
+ "height": 720,
+ "width": 1280
+ }],
+ "startedAt": "2020-08-05T08:38:37.589Z",
+ "duration": 1171,
+ "videoTimestamp": 4486
+ }]
+ }],
"video": "User/janelane/my-app/cypress/videos/abc123.mp4"
}],
"runUrl": "https://dashboard.cypress.io/projects/def456/runs/12",
@@ -103,9 +141,9 @@ cypress.run({
"totalFailed": 1,
"totalPassed": 0,
"totalPending": 0,
- "totalSkipped": 12,
- "totalSuites": 8,
- "totalTests": 13,
+ "totalSkipped": 0,
+ "totalSuites": 1,
+ "totalTests": 1,
}
```
@@ -198,6 +236,7 @@ node ./wrapper cypress run --browser chrome --config ...
We use CLI parsing and calling `cypress.run` to {% url "repeat tests to find flaky recipes" https://github.com/cypress-io/cypress-example-recipes/blob/master/test-repeat.js %} and to {% url "validate test numbers after a test run" https://github.com/bahmutov/cypress-react-unit-test/blob/main/scripts/cypress-expect.js %}.
{% history %}
+{% url "5.0.0" changelog %} | Test results returned from `cypress.run()` changed.
{% url "4.11.0" changelog#4-11-0 %} | Added `cypress.cli` with `parseRunArguments` function.
{% url "4.9.0" changelog#4-9-0 %} | Added `quiet` option to `cypress.run()`
{% endhistory %}
diff --git a/source/guides/guides/test-retries.md b/source/guides/guides/test-retries.md
new file mode 100644
index 0000000000..c91ff1a16c
--- /dev/null
+++ b/source/guides/guides/test-retries.md
@@ -0,0 +1,196 @@
+---
+title: Test Retries
+---
+
+{% note info %}
+# {% fa fa-graduation-cap %} What you'll learn
+
+- What are test retries?
+- Why are test retries important?
+- How to configure test retries
+{% endnote %}
+
+# Introduction
+
+End-to-end (E2E) tests excel at testing complex systems. However, there are still behaviors that are hard to verify and make tests flaky (i.e., unreliable) and fail sometimes due to unpredictable conditions (eg., temporary outages in external dependencies, random network errors, etc.). Some other common race conditions that could result in unreliable tests include:
+
+- Animations
+- API calls
+- Test server / database availability
+- Resource dependencies availability
+- Network issues
+
+With test retries, Cypress is able to retry failed tests to help reduce test flakiness and continuous integration (CI) build failures. By doing so, this will save your team valuable time and resources so you can focus on what matters most to you.
+
+# How It Works
+
+By default, tests will not retry when they fail. You will need to {% urlHash "enable test retries in your configuration" Configure-Test-Retries %} to use this feature.
+
+Once test retries are enabled, tests can be configured to have X number of retry attempts. For example, if test retries has been configured with `2` retry attempts, Cypress will retry tests up to 2 additional times (for a total of 3 attempts) before potentially being marked as a failed test.
+
+When each test is run again, the following {% url "hooks" writing-and-organizing-tests#Hooks %} will be re-run also:
+
+- `beforeEach`
+- `afterEach`
+
+{% note warning %}
+However, failures in `before` and `after` hooks will not trigger a retry.
+{% endnote %}
+
+**The following is a detailed step-by-step example of how test retries works:**
+
+Assuming we have configured test retries with `2` retry attempts (for a total of 3 attempts), here is how the tests might run:
+
+1. A test runs for the first time. If the {% fa fa-check-circle green %} test passes, Cypress will move forward with any remaining tests as usual.
+
+2. If the {% fa fa-times red %} test fails, Cypress will tell you that the first attempt failed and will to run the test a second time.
+
+{% img /img/guides/test-retries/attempt-2-start.png %}
+
+3. If the {% fa fa-check-circle green %} test passes after the second attempt, Cypress will continue with any remaining tests.
+
+4. If the {% fa fa-times red %} test fails a second time, Cypress will make the final third attempt to re-run the test.
+
+{% img /img/guides/test-retries/attempt-3-start.png %}
+
+5. If the {% fa fa-times red %} test fails a third time, Cypress will mark the test as failed and then move on to run any remaining tests.
+
+{% img /img/guides/test-retries/attempt-3-fail.png %}
+
+The following is a screen capture of what test retries looks like on the same failed test when run via {% url "`cypress run`" command-line#cypress-run %}.
+
+{% img /img/guides/test-retries/cli-error-message.png %}
+
+During {% url "`cypress open`" command-line#cypress-open %} you will be able to see the number of attempts made in the {% url "Command Log" test-runner#Command-Log %} and expand each attempt for review and debugging if desired.
+
+{% video local /img/guides/test-retries/attempt-expand-collapse-time-travel.mp4 %}
+
+# Configure Test Retries
+
+## Global Configuration
+
+Typically you will want to define different retry attempts for `cypress run` versus `cypress open`. You can configure this in your {% url "configuration file" command-line#cypress-open-config-file-lt-config-file-gt %} (`cypress.json` by default) by passing the `retries` option an object with the following options:
+
+- `runMode` allows you to define the number of test retries when running `cypress run`
+- `openMode` allows you to define the number of test retries when running `cypress open`
+
+```jsx
+{
+ "retries": {
+ // Configure retry attempts for `cypress run`
+ // Default is 0
+ "runMode": 2,
+ // Configure retry attempts for `cypress open`
+ // Default is 0
+ "openMode": 0
+ }
+}
+```
+
+### Configure retry attempts for all modes
+
+If you want to configure the retry attempts for all tests run in both `cypress run` and `cypress open`, you can configure this in your {% url "configuration file" command-line#cypress-open-config-file-lt-config-file-gt %} (`cypress.json` by default) by defining the `retries` property and setting the desired number of retries.
+
+```jsx
+{
+ "retries": 1
+}
+```
+
+## Custom Configurations
+
+### Individual Test(s)
+
+If you want to configure retry attempts on a specific test, you can set this by using the {% url "test's configuration" writing-and-organizing-tests#Test-Configuration %}.
+
+```jsx
+// Customize retry attempts for an individual test
+describe('User sign-up and login', () => {
+ // `it` test block with no custom configuration
+ it('should redirect unauthenticated user to sign-in page', () => {
+ // ...
+ })
+
+ // `it` test block with custom configuration
+ it('allows user to login', {
+ retries: {
+ runMode: 2,
+ openMode: 1
+ }
+ }, () => {
+ // ...
+ })
+})
+```
+
+### Test Suite(s)
+
+If you want to configure try attempts for a suite of tests, you can do this by setting the suite's configuration.
+
+```jsx
+// Customizing retry attempts for a suite of tests
+describe('User bank accounts', {
+ retries: {
+ runMode: 2,
+ openMode: 1,
+ }
+}, () => {
+ // The per-suite configuration is applied to each test
+ // If a test fails, it will be retried
+ it('allows a user to view their transactions, () => {
+ // ...
+ }
+
+ it('allows a user to edit their transactions, () => {
+ // ...
+ }
+})
+```
+
+You can find more information about custom configurations here: {% url "Test Configuration" configuration#Test-Configuration %}
+
+# Screenshots
+
+When a test retries, Cypress will continue to take screenshots for each failed attempt or {% url "`cy.screenshot()`" screenshot %} and suffix each new screenshot with `(attempt n)`, corresponding to the current retry attempt number.
+
+With the following test code, you would see the below screenshot filenames when all 3 attempts fail:
+
+```js
+describe('User Login', () => {
+ it('displays login errors', () => {
+ cy.visit('/')
+ cy.screenshot('user-login-errors')
+ // ...
+ })
+})
+```
+
+```js
+// screenshot filename from cy.screenshot() on 1st attempt
+'user-login-errors.png'
+// screenshot filename on 1st failed attempt
+'user-login-errors (failed).png'
+// screenshot filename from cy.screenshot() on 2nd attempt
+'user-login-errors (attempt 2).png'
+// screenshot filename on 2nd failed attempt
+'user-login-errors (failed) (attempt 2).png'
+// screenshot filename from cy.screenshot() on 3rd attempt
+'user-login-errors (attempt 3).png'
+// screenshot filename on 3rd failed attempt
+'user-login-errors (failed) (attempt 3).png'
+```
+
+# Dashboard
+
+If you are using the {% url "Cypress Dashboard" dashboard %}, information related to test retries is not currently shown. Showing this information and other analytics related to test retries is on our {% url "product roadmap" https://cypress-io.productboard.com/roadmap/1238172-product-roadmap %}.
+
+
+# Frequently Asked Questions (FAQs)
+
+## Will retried tests be counted as more than one test recording in my billing?
+
+No. Tests recorded during `cypress run` with the `--record` flag will be counted the same with or without test retries.
+
+We consider each time the `it()` function is called to be a single test for billing purposes. The test retrying will not count as extra test recordings in your billing.
+
+You can always see how many tests you've recorded from your organization's Billing & Usage page within the {% url "Dashboard" https://on.cypress.io/dashboard %}.
diff --git a/source/guides/overview/key-differences.md b/source/guides/overview/key-differences.md
index 4c3ebebf6c..bdfd54ce9f 100644
--- a/source/guides/overview/key-differences.md
+++ b/source/guides/overview/key-differences.md
@@ -37,7 +37,7 @@ Having ultimate control over your application, the network traffic, and native a
- Test how your application responds to errors on your server by {% url "modifying response status codes to be 500" route %}.
- Modify DOM elements directly - like forcing hidden elements to be shown.
- Use 3rd party plugins programmatically. Instead of fussing with complex UI widgets like multi selects, autocompletes, drop downs, tree views or calendars, you can call methods directly from your test code to control them.
-- {% url "Prevent Google Analytics from loading *before* any of your application code executes" configuration#blacklistHosts %} when testing.
+- {% url "Prevent Google Analytics from loading *before* any of your application code executes" configuration#blockhosts %} when testing.
- Get synchronous notifications whenever your application transitions to a new page or when it begins to unload.
- {% url "Control time by moving forward or backward" clock %} so that timers or polls automatically fire without having to wait for the required time in your tests.
- Add your own event listeners to respond to your application. You could update your application code to behave differently when under tests in Cypress. You can control WebSocket messages from within Cypress, conditionally load 3rd party scripts, or call functions directly on your application.
diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md
index d215a79cba..40bc9640f7 100644
--- a/source/guides/references/configuration.md
+++ b/source/guides/references/configuration.md
@@ -22,6 +22,7 @@ Option | Default | Description
`port` | `null` | Port used to host Cypress. Normally this is a randomly generated port
`reporter` | `spec` | The {% url 'reporter' reporters %} used during `cypress run`
`reporterOptions` | `null` | The {% url 'reporter options' reporters#Reporter-Options %} used. Supported options depend on the reporter.
+`retries` | `{ "runMode": 0, "openMode": 0 }` | The number of times to retry a failing test. Can be configured to apply to `cypress run` or `cypress open` separately. See {% url "Test Retries" test-retries %} for more information.
`watchForFileChanges` | `true` | Whether Cypress will watch and restart tests on test file changes
## Timeouts
@@ -78,7 +79,7 @@ Option | Default | Description
Option | Default | Description
----- | ---- | ----
`chromeWebSecurity` | `true` | Whether to enable Chromium-based browser's Web Security for same-origin policy and insecure mixed content. {% url 'Read more about Web Security' web-security %}.
-`blacklistHosts` | `null` | A String or Array of hosts that you wish to block traffic for. {% urlHash 'Please read the notes for examples on using this.' blacklistHosts %}
+`blockHosts` | `null` | A String or Array of hosts that you wish to block traffic for. {% urlHash 'Please read the notes for examples on using this.' blockHosts %}
`firefoxGcInterval` | `{ "runMode": 1, "openMode": null }` | Controls whether Cypress forces Firefox to run garbage collection (GC) cleanup and how frequently. During {% url "`cypress run`" command-line#cypress-run %}, the default value is `1`. During {% url "`cypress open`" command-line#cypress-open %}, the default value is `null`. See full details {% urlHash "here" firefoxGcInterval %}.
`modifyObstructiveCode` | `true` | Whether Cypress will search for and replace obstructive JS code in `.js` or `.html` files. {% urlHash 'Please read the notes for more information on this setting.' modifyObstructiveCode %}
`userAgent` | `null` | Enables you to override the default user agent the browser sends in all request headers. User agent values are typically used by servers to help identify the operating system, browser, and browser version. See {% url "User-Agent MDN Documentation" https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent %} for example user agent values.
@@ -216,19 +217,21 @@ The configuration values passed in will only take effect during the suite or tes
### Suite configuration
-You can configure the size of the viewport height and width within a suite.
+You can configure the number of times to retries a suite of tests if they fail during `cypress run` and `cypress open` separately.
```js
-describe('page display on medium size screen', {
- viewportHeight: 1000,
- viewportWidth: 400
+describe('login', {
+ retries: {
+ runMode: 3,
+ openMode: 2
+ }
}, () => {
- it('does not display sidebar', () => {
- cy.get('#sidebar').should('not.be.visible')
+ it('should redirect unauthenticated user to sign-in page', () => {
+ // ...
})
- it('shows hamburger menu', () => {
- cy.get('#header').find('i.menu').should('be.visible')
+ it('allows user to login', () => {
+ // ...
})
})
```
@@ -259,7 +262,7 @@ When you open a Cypress project, clicking on the **Settings** tab will display t
# Notes
-## `blacklistHosts`
+## blockHosts
By passing a string or array of strings you can block requests made to one or more hosts.
@@ -308,7 +311,7 @@ For instance given a URL: `https://google.com/search?q=cypress`
- {% fa fa-exclamation-triangle red %} Does NOT match `*.google.com`
{% endnote %}
-When Cypress blocks a request made to a matching host, it will automatically send a `503` status code. As a convenience it also sets a `x-cypress-matched-blacklist-host` header so you can see which rule it matched.
+When Cypress blocks a request made to a matching host, it will automatically send a `503` status code. As a convenience it also sets a `x-cypress-matched-blocked-host` header so you can see which rule it matched.
{% imgTag /img/guides/blocked-host.png "Network tab of dev tools with analytics.js request selected and the response header highlighted " %}
@@ -395,9 +398,11 @@ Run GC cleanup before every 3rd test during {% url "`cypress run`" command-line#
IntelliSense is available for Cypress while editing your configuration file. {% url "Learn how to set up Intelligent Code Completion." IDE-integration#Intelligent-Code-Completion %}
{% history %}
-{% url "4.1.0" changelog#4-12-0 %} | Added support for `screenshotOnRunFailure` configuration.
-{% url "4.0.0" changelog#4-0-0 %} | Added support for `firefoxGcInterval` configuration.
-{% url "3.5.0" changelog#3-5-0 %} | Added support for `nodeVersion` configuration.
+{% url "5.0.0" changelog %} | Added `retries` configuration.
+{% url "5.0.0" changelog %} | Renamed `blacklistHosts` configuration to `blockHosts`.
+{% url "4.1.0" changelog#4-12-0 %} | Added `screenshotOnRunFailure` configuration.
+{% url "4.0.0" changelog#4-0-0 %} | Added `firefoxGcInterval` configuration.
+{% url "3.5.0" changelog#3-5-0 %} | Added `nodeVersion` configuration.
{% endhistory %}
# See also
diff --git a/source/guides/references/experiments.md b/source/guides/references/experiments.md
index 8e5714dc44..60a89e48d4 100644
--- a/source/guides/references/experiments.md
+++ b/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`.
diff --git a/source/guides/references/migration-guide.md b/source/guides/references/migration-guide.md
index a673824211..e671ac3a51 100644
--- a/source/guides/references/migration-guide.md
+++ b/source/guides/references/migration-guide.md
@@ -2,9 +2,395 @@
title: Migration Guide
---
+# Migrating to Cypress 5.0
+
+This guide details the changes and how to change your code to migrate to Cypress 5.0. {% url "See the full changelog for 5.0" changelog#5-0-0 %}.
+
+## Tests retries
+
+Test retries are available in Cypress 5.0. This means that tests can be re-run a number of times before potentially being marked as a failed test. Read the Test Retries doc for more information on how this works and how to turn on test retries.
+
+When test retries are turned on, there will now be a screenshot taken for every failed attempt, so there could potentially be more than 1 screenshot per test failure. Read the Test Retries doc for more information on how this works.
+
+The {% url "`cypress-plugin-retries`" https://github.com/Bkucera/cypress-plugin-retries %} plugin has been deprecated in favor of test retries built into Cypress. There's guidance below on how to migrate from the {% url "`cypress-plugin-retries`" https://github.com/Bkucera/cypress-plugin-retries %} plugin to Cypress's built-in test retries.
+
+### Configure test retries via the CLI
+
+{% badge danger Before %} Setting retries with `cypress-plugin-retries` via env vars
+
+```shell
+CYPRESS_RETRIES=2 cypress run
+```
+
+{% badge success After %} Setting test retries in Cypress 5.0 via via env vars
+
+```shell
+CYPRESS_RETRIES=2 cypress run
+```
+
+### Configure test retries in the configuration file
+
+{% badge danger Before %} Setting retries with `cypress-plugin-retries` via configuration
+
+```json
+{
+ "env":
+ {
+ "RETRIES": 2
+ }
+}
+```
+
+{% badge success After %} Setting test retries in Cypress 5.0 via configuration
+
+```json
+{
+ "retries": 1
+}
+```
+
+- `runMode` allows you to define the number of test retries when running `cypress run`
+- `openMode` allows you to define the number of test retries when running `cypress open`
+
+```json
+{
+ "retries": {
+ "runMode": 1,
+ "openMode": 3
+ }
+}
+```
+
+### Configure test retries per test
+
+{% badge danger Before %} Setting retries with `cypress-plugin-retries` via the test
+
+```js
+it('test', () => {
+ Cypress.currentTest.retries(2)
+})
+```
+
+{% badge success After %} Setting test retries in Cypress 5.0 via test options
+
+```js
+it('allows user to login', {
+ retries: 2
+}, () => {
+ // ...
+})
+```
+
+- `runMode` allows you to define the number of test retries when running `cypress run`
+- `openMode` allows you to define the number of test retries when running `cypress open`
+
+```js
+it('allows user to login', {
+ retries: {
+ runMode: 2,
+ openMode: 3
+ }
+}, () => {
+ // ...
+})
+```
+
+## Module API results
+
+To more accurately reflect result data for runs with test retries, the structure of each run's `runs` array resolved from the `Promise` returned from `cypress.run()` of the Module API has changed.
+
+Mainly there is a new `attempts` Array on each `test` which will reflect the result of each test retry.
+
+{% badge danger Before %} `results.runs` Module API results
+
+```json
+{
+ // ...
+ "runs": [{
+ // ...
+ "hooks": [{
+ "hookId": "h1",
+ "hookName": "before each",
+ "title": [ "before each hook" ],
+ "body": "function () {\n expect(true).to.be["true"];\n}"
+ }],
+ // ...
+ "screenshots": [{
+ "screenshotId": "8ddmk",
+ "name": null,
+ "testId": "r2",
+ "takenAt": "2020-08-05T08:52:20.432Z",
+ "path": "User/janelane/my-app/cypress/screenshots/spec.js/test (failed).png",
+ "height": 720,
+ "width": 1280
+ }],
+ "stats": {
+ // ...
+ "wallClockStartedAt": "2020-08-05T08:38:37.589Z",
+ "wallClockEndedAt": "2018-07-11T17:53:35.675Z",
+ "wallClockDuration": 1171
+ },
+ "tests": [{
+ "testId": "r2",
+ "title": [ "test" ],
+ "state": "failed",
+ "body": "function () {\n expect(true).to.be["false"];\n}",
+ "stack": "AssertionError: expected true to be false\n' +
+ ' at Context.eval (...cypress/integration/spec.js:5:21",
+ "error": "expected true to be false",
+ "timings": {
+ "lifecycle": 16,
+ "test": {...}
+ },
+ "failedFromHookId": null,
+ "wallClockStartedAt": "2020-08-05T08:38:37.589Z",
+ "wallClockDuration": 1171,
+ "videoTimestamp": 4486
+ }],
+ }],
+ // ...
+}
+```
+
+{% badge success After %} `results.runs` Module API results
+
+```json
+{
+ // ...
+ "runs": [{
+ // ...
+ "hooks": [{
+ "hookName": "before each",
+ "title": [ "before each hook" ],
+ "body": "function () {\n expect(true).to.be["true"];\n}"
+ }],
+ // ...
+ "stats": {
+ // ...
+ "startedAt": "2020-08-05T08:38:37.589Z",
+ "endedAt": "2018-07-11T17:53:35.675Z",
+ "duration": 1171
+ },
+ "tests": [{
+ "title": [ "test" ],
+ "state": "failed",
+ "body": "function () {\n expect(true).to.be["false"];\n}",
+ "displayError": "AssertionError: expected true to be false\n' +
+ ' at Context.eval (...cypress/integration/spec.js:5:21",
+ "attempts": [{
+ "state": "failed",
+ "error": {
+ "message": "expected true to be false",
+ "name": "AssertionError",
+ "stack": "AssertionError: expected true to be false\n' +
+ ' at Context.eval (...cypress/integration/spec.js:5:21"
+ },
+ "screenshots": [{
+ "name": null,
+ "takenAt": "2020-08-05T08:52:20.432Z",
+ "path": "User/janelane/my-app/cypress/screenshots/spec.js/test (failed).png",
+ "height": 720,
+ "width": 1280
+ }],
+ "startedAt": "2020-08-05T08:38:37.589Z",
+ "duration": 1171,
+ "videoTimestamp": 4486
+ }]
+ }],
+ }],
+ // ...
+}
+```
+
+## Cookies `whitelist` option renamed
+
+The {% url "`Cypress.Cookies.defaults()`" cookies %} `whitelist` option has been renamed to `preserve` to more closely reflect its behavior.
+
+{% badge danger Before %} `whitelist` option
+
+```js
+Cypress.Cookies.defaults({
+ whitelist: 'session_id'
+})
+```
+
+{% badge success After %} `preserve` option
+
+```js
+Cypress.Cookies.defaults({
+ preserve: 'session_id'
+})
+```
+
+## `blacklistHosts` configuration renamed
+
+The `blacklistHosts` configuration has been renamed to {% url "`blockHosts`" configuration#Notes %} to more closely reflect its behavior.
+
+This should be updated in all places where Cypress configuration can be set including the via the configuration file (`cypress.json` by default), command line arguments, the `pluginsFile`, `Cypress.config()` or environment variables.
+
+{% badge danger Before %} `blacklistHosts` configuration in `cypress.json`
+
+```json
+{
+ "blacklistHosts": "www.google-analytics.com"
+}
+```
+
+{% badge success After %} `blockHosts` configuration in `cypress.json`
+
+```json
+{
+ "blockHosts": "www.google-analytics.com"
+}
+```
+
+## Return type of `Cypress.Blob` changed
+
+We updated the {% url 'Blob' https://github.com/nolanlawson/blob-util %} library used behind {% url "`Cypress.Blob`" blob %} from `1.3.3` to `2.0.2`.
+
+The return type of the {% url "`Cypress.Blob`" blob %} methods `arrayBufferToBlob`, `base64StringToBlob`, `binaryStringToBlob`, and `dataURLToBlob` have changed from `Promise` to `Blob`.
+
+{% badge danger Before %} `Cypress.Blob` methods returned a Promise
+
+```js
+Cypress.Blob.base64StringToBlob(this.logo, 'image/png')
+.then((blob) => {
+ // work with the returned blob
+})
+```
+
+{% badge success After %} `Cypress.Blob` methods return a Blob
+
+```js
+const blob = Cypress.Blob.base64StringToBlob(this.logo, 'image/png')
+
+// work with the returned blob
+```
+
+## `cy.server()` `whitelist` option renamed
+
+The {% url "`cy.server()`" server %} `whitelist` option has been renamed to `ignore` to more closely reflect its behavior.
+
+{% badge danger Before %} `whitelist` option
+
+```js
+cy.server({
+ whitelist: (xhr) => {
+ return xhr.method === 'GET' && /\.(jsx?|html|css)(\?.*)?$/.test(xhr.url)
+ }
+})
+```
+
+{% badge success After %} `ignore` option
+
+```js
+cy.server({
+ ignore: (xhr) => {
+ return xhr.method === 'GET' && /\.(jsx?|html|css)(\?.*)?$/.test(xhr.url)
+ }
+})
+```
+
+## Cookies `sameSite` property
+
+Values yielded by {% url "`cy.setCookie()`" setcookie %}, {% url "`cy.getCookie()`" getcookie %}, and {% url "`cy.getCookies()`" getcookies %} will now contain the `sameSite` property if specified.
+
+If you were using the `experimentalGetCookiesSameSite` configuration to get the `sameSite` property previously, this should be removed.
+
+{% badge danger Before %} Cookies yielded before had no `sameSite` property.
+
+```js
+cy.getCookie('token').then((cookie) => {
+ // cy.getCookie() yields a cookie object
+ // {
+ // domain: "localhost",
+ // expiry: 1593551644,
+ // httpOnly: false,
+ // name: "token",
+ // path: "/commands",
+ // secure: false,
+ // value: "123ABC"
+ // }
+})
+```
+
+{% badge success After %} Cookies yielded now have `sameSite` property if specified.
+
+```js
+cy.getCookie('token').then((cookie) => {
+ // cy.getCookie() yields a cookie object
+ // {
+ // domain: "localhost",
+ // expiry: 1593551644,
+ // httpOnly: false,
+ // name: "token",
+ // path: "/commands",
+ // sameSite: "strict",
+ // secure: false,
+ // value: "123ABC"
+ // }
+})
+```
+
+## __dirname / __filename
+
+The globals `__dirname` and `__filename` no longer include a leading slash.
+
+{% badge danger Before %} `__dirname` / `__filename`
+
+```js
+// cypress/integration/app_spec.js
+it('include leading slash < 5.0', () => {
+ expect(__dirname).to.equal('/cypress/integration')
+ expect(__filename).to.equal('/cypress/integration/app_spec.js')
+})
+```
+
+{% badge success After %} `__dirname` / `__filename`
+
+```js
+// cypress/integration/app_spec.js
+it('do not include leading slash >= 5.0', () => {
+ expect(__dirname).to.equal('cypress/integration')
+ expect(__filename).to.equal('cypress/integration/app_spec.js')
+})
+```
+
+## Linux dependencies
+
+Running Cypress on Linux now requires the `libgbm` dependency (on Debian-based systems, this is available as `libgbm-dev`). To install all required dependencies on Ubuntu/Debian, you can run the script below:
+
+```shell
+apt-get install libgtk2.0-0 libgtk-3-0 libgbm-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2 libxtst6 xauth xvfb
+```
+
+## TypeScript esModuleInterop
+
+Cypress no longer forces the `esModuleInterop` compiler option for TypeScript to be `true` for spec, support, and plugin files. We recommend setting it in your project's `tsconfig.json` instead if you need to.
+
+```json
+// tsconfig.json
+{
+ "compilerOptions": {
+ "esModuleInterop": true,
+ /* ... other compiler options ... */
+ }
+}
+```
+
+## TypeScript 3.4+ support
+
+Cypress 5.0 raises minimum required TypeScript version from 2.9+ to 3.4+. You'll need to have TypeScript 3.4+ installed within your project to have TypeScript support within Cypress.
+
+## Node.js 10+ support
+
+Cypress comes bundled with it's own {% url "Node.js version" https://github.com/cypress-io/cypress/blob/develop/.node-version %}. However, installing the `cypress` npm package uses the Node.js version installed on your system.
+
+Node.js 8 reached its end of life on Dev 31, 2019. {% url "See Node's release schedule" https://github.com/nodejs/Release %}. This Node.js version will no longer be supported when installing Cypress. The minimum Node.js version supported to install Cypress is Node.js 10.
+
# Migrating to Cypress 4.0
-This guide details the changes and how to change your code to migrate to Cypress 4.0.
+This guide details the changes and how to change your code to migrate to Cypress 4.0. {% url "See the full changelog for 4.0" changelog#4-0-0 %}.
## Mocha upgrade
diff --git a/source/guides/tooling/plugins-guide.md b/source/guides/tooling/plugins-guide.md
index f1140d3270..a0958b8764 100644
--- a/source/guides/tooling/plugins-guide.md
+++ b/source/guides/tooling/plugins-guide.md
@@ -34,14 +34,15 @@ Check out our {% url 'Configuration API docs' configuration-api %} which describ
## Preprocessors
-The event `file:preprocessor` is used to customize how your test code is transpiled and sent to the browser. By default Cypress handles CoffeeScript and ES6 using `babel` and then uses `browserify` to package it for the browser.
+The event `file:preprocessor` is used to customize how your test code is transpiled and sent to the browser. By default, Cypress handles ES2015+, TypeScript, and CoffeeScript, using webpack to package it for the browser.
You can use the `file:preprocessor` event to do things like:
- Add the latest ES* support.
- Write your test code in ClojureScript.
-- Customize the `babel` settings to add your own plugins.
-- Swap out `browserify` for `webpack` or anything else.
+- Customize the Babel settings to add your own plugins.
+- Customize the options for compiling TypeScript.
+- Swap out webpack for Browserify or anything else.
Check out our {% url 'File Preprocessor API docs' preprocessors-api %} which describe how to use this event.
diff --git a/source/guides/tooling/typescript-support.md b/source/guides/tooling/typescript-support.md
index e2319aa41b..62ae53d110 100644
--- a/source/guides/tooling/typescript-support.md
+++ b/source/guides/tooling/typescript-support.md
@@ -6,7 +6,7 @@ Cypress ships with {% url "official type declarations" https://github.com/cypres
## Install TypeScript
-You'll need to have TypeScript installed within your project to have TypeScript support within Cypress.
+You'll need to have TypeScript 3.4+ installed within your project to have TypeScript support within Cypress.
```bash
npm install typescript
@@ -129,6 +129,7 @@ module.exports = (on, config) => {
```
{% history %}
+{% url "5.0.0" changelog#5-0-0 %} | Raised minimum required TypeScript version from 2.9+ to 3.4+
{% url "4.4.0" changelog#4-4-0 %} | Added support for TypeScript without needing your own transpilation through preprocessors.
{% endhistory %}
diff --git a/themes/cypress/languages/en.yml b/themes/cypress/languages/en.yml
index dde4b355a2..fcf9545ca4 100644
--- a/themes/cypress/languages/en.yml
+++ b/themes/cypress/languages/en.yml
@@ -48,6 +48,7 @@ sidebar:
screenshots-and-videos: Screenshots and Videos
guides: Guides
command-line: Command Line
+ test-retries: Test Retries
continuous-integration: Continuous Integration
parallelization: Parallelization
environment-variables: Environment Variables
diff --git a/themes/cypress/languages/es.yml b/themes/cypress/languages/es.yml
index 1004f7b29b..6e8958e094 100644
--- a/themes/cypress/languages/es.yml
+++ b/themes/cypress/languages/es.yml
@@ -48,6 +48,7 @@ sidebar:
screenshots-and-videos: Capturas de pantalla y videos
guides: Guías
command-line: Línea de comandos
+ test-retries: Test Retries
continuous-integration: Integración Continua
parallelization: Paralelización
environment-variables: Variables de entorno
diff --git a/themes/cypress/languages/ja.yml b/themes/cypress/languages/ja.yml
index 19492c441f..8cd4f1f8e7 100644
--- a/themes/cypress/languages/ja.yml
+++ b/themes/cypress/languages/ja.yml
@@ -48,6 +48,7 @@ sidebar:
screenshots-and-videos: スクリーンショットとビデオ
guides: ガイド
command-line: コマンドライン
+ test-retries: Test Retries
continuous-integration: 継続的インテグレーション
parallelization: Parallelization
environment-variables: 環境変数
diff --git a/themes/cypress/languages/pt-br.yml b/themes/cypress/languages/pt-br.yml
index 3709fabf08..e67c793c86 100644
--- a/themes/cypress/languages/pt-br.yml
+++ b/themes/cypress/languages/pt-br.yml
@@ -48,6 +48,7 @@ sidebar:
screenshots-and-videos: Screenshots e Vídeos
guides: Guias
command-line: Linha de Comando
+ test-retries: Test Retries
continuous-integration: Integração Contínua
parallelization: Paralelização
environment-variables: Variáveis de Ambiente
diff --git a/themes/cypress/languages/ru.yml b/themes/cypress/languages/ru.yml
index d2d986361d..6c60b0ec6a 100644
--- a/themes/cypress/languages/ru.yml
+++ b/themes/cypress/languages/ru.yml
@@ -48,6 +48,7 @@ sidebar:
screenshots-and-videos: Скриншоты и видео
guides: Руководства
command-line: Командная строка
+ test-retries: Test Retries
continuous-integration: Непрерывная интеграция
parallelization: Параллелизация
environment-variables: Переменные среды
diff --git a/themes/cypress/languages/zh-cn.yml b/themes/cypress/languages/zh-cn.yml
index facac61058..8a4ece0e85 100644
--- a/themes/cypress/languages/zh-cn.yml
+++ b/themes/cypress/languages/zh-cn.yml
@@ -50,6 +50,7 @@ sidebar:
screenshots-and-videos: 截图和视频
guides: 指南
command-line: 命令行
+ test-retries: Test Retries
continuous-integration: 持续集成
parallelization: 并行化
environment-variables: 环境变量
diff --git a/themes/cypress/source/img/guides/test-retries/attempt-1-fail.png b/themes/cypress/source/img/guides/test-retries/attempt-1-fail.png
new file mode 100644
index 0000000000..88699cf7a7
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/attempt-1-fail.png differ
diff --git a/themes/cypress/source/img/guides/test-retries/attempt-2-start.png b/themes/cypress/source/img/guides/test-retries/attempt-2-start.png
new file mode 100644
index 0000000000..0befae33aa
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/attempt-2-start.png differ
diff --git a/themes/cypress/source/img/guides/test-retries/attempt-3-fail.png b/themes/cypress/source/img/guides/test-retries/attempt-3-fail.png
new file mode 100644
index 0000000000..5f509c3559
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/attempt-3-fail.png differ
diff --git a/themes/cypress/source/img/guides/test-retries/attempt-3-start.png b/themes/cypress/source/img/guides/test-retries/attempt-3-start.png
new file mode 100644
index 0000000000..4787a64dd0
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/attempt-3-start.png differ
diff --git a/themes/cypress/source/img/guides/test-retries/attempt-expand-collapse-time-travel.mp4 b/themes/cypress/source/img/guides/test-retries/attempt-expand-collapse-time-travel.mp4
new file mode 100644
index 0000000000..dd2fad7305
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/attempt-expand-collapse-time-travel.mp4 differ
diff --git a/themes/cypress/source/img/guides/test-retries/cli-error-message.png b/themes/cypress/source/img/guides/test-retries/cli-error-message.png
new file mode 100644
index 0000000000..66f1e7e49a
Binary files /dev/null and b/themes/cypress/source/img/guides/test-retries/cli-error-message.png differ