diff --git a/source/api/cypress-api/screenshot-api.md b/source/api/cypress-api/screenshot-api.md index 553084f036..659784e8b0 100644 --- a/source/api/cypress-api/screenshot-api.md +++ b/source/api/cypress-api/screenshot-api.md @@ -29,7 +29,7 @@ Option | Default | Description `capture` | `'fullPage'` | Which parts of the Test Runner to capture. This value is ignored for element screenshot captures. Valid values are `viewport`, `fullPage`, or `runner`. When `viewport`, your application under test is captured in the current viewport. When `fullPage`, your application under test is captured in its entirety from top to bottom. When `runner`, the entire browser viewport, including the Cypress Command Log, is captured. For screenshots automatically taken on test failure, capture is always coerced to `runner`. `disableTimersAndAnimations` | `true`| When true, prevents JavaScript timers (`setTimeout`, `setInterval`, etc) and CSS animations from running while the screenshot is taken. `scale` | `false` | Whether to scale the app to fit into the browser viewport. This is always coerced to `true` for `runner` captures. -`screenshotOnRunFailure` | `true` | When true, automatically takes a screenshot when there is a failure in Run mode. +`screenshotOnRunFailure` | `true` | When true, automatically takes a screenshot when there is a failure during `cypress run`. `onBeforeScreenshot` | `null` | A callback before a (non-failure) screenshot is taken. For an element capture, the argument is the element being captured. For other screenshots, the argument is the `$el`. `onAfterScreenshot` | `null` | A callback after a (non-failure) screenshot is taken. For an element capture, the first argument is the element being captured. For other screenshots, the first argument is the `$el`. The second argument is properties concerning the screenshot, including the path it was saved to and the dimensions of the saved screenshot. diff --git a/source/api/plugins/writing-a-plugin.md b/source/api/plugins/writing-a-plugin.md index 896cc664b9..c84aea9307 100644 --- a/source/api/plugins/writing-a-plugin.md +++ b/source/api/plugins/writing-a-plugin.md @@ -68,6 +68,7 @@ The `config` object also includes the following extra values that are not part o * `configFile`: The absolute path to the config file. By default, this is `/cypress.json`, but may be a custom path or `false` if using the {% url "`--config-file` flag" command-line#cypress-open-config-file-lt-config-file-gt %}. * `projectRoot`: The absolute path to the root of the project (e.g. `/Users/me/dev/my-project`) +* `version`: The version number of Cypress. This can be used to handle breaking changes. {% endnote %} {% url "Please check out our API docs for modifying configuration here." configuration-api %} diff --git a/source/guides/guides/debugging.md b/source/guides/guides/debugging.md index b9bfa96bf0..ae92a6ce9d 100644 --- a/source/guides/guides/debugging.md +++ b/source/guides/guides/debugging.md @@ -158,3 +158,13 @@ While learning Cypress it may be a good idea to try small tests against some HTM # Troubleshooting Cypress There are times when you will encounter errors or unexpected behavior with Cypress itself. In this situation, we recommend checking out our {% url "Troubleshooting Guide" troubleshooting %}. + +# More info + +Often debugging a failing Cypress test means understanding better how your own application works, and how the application might race against the test commands. We recommend reading these blog posts where we show common error scenarios and how to solve them: + +- {% url "When Can The Test Start?" https://www.cypress.io/blog/2018/02/05/when-can-the-test-start/ %} +- {% url "When Can The Test Stop?" https://www.cypress.io/blog/2020/01/16/when-can-the-test-stop/ %} +- {% url "When Can The Test Click?" https://www.cypress.io/blog/2019/01/22/when-can-the-test-click/ %} +- {% url "When Can The Test Log Out?" https://www.cypress.io/blog/2020/06/25/when-can-the-test-log-out/ %} +- {% url "Do Not Get Too Detached" https://www.cypress.io/blog/2020/07/22/do-not-get-too-detached/ %} diff --git a/source/guides/guides/screenshots-and-videos.md b/source/guides/guides/screenshots-and-videos.md index 5e4aad1eb0..0019eaaac1 100644 --- a/source/guides/guides/screenshots-and-videos.md +++ b/source/guides/guides/screenshots-and-videos.md @@ -19,7 +19,7 @@ To take a manual screenshot you can use the {% url `cy.screenshot()` screenshot Additionally, Cypress will automatically capture screenshots when a failure happens during `cypress run`. Screenshots on failure are *not* automatically taken during `cypress open`. -This behavior can be turned off by setting `screenshotOnRunFailure` to `false` in the {% url 'Cypress.Screenshot.defaults()' screenshot-api %}. +Capturing of screenshots when a test fails can be turned off entirely by setting {% url `screenshotOnRunFailure` configuration#Screenshots %} to `false` from within your {% url "configuration" configuration %} or by setting `screenshotOnRunFailure` to `false` in the {% url 'Cypress.Screenshot.defaults()' screenshot-api %}. Screenshots are stored in the {% url `screenshotsFolder` configuration#Screenshots %} which is set to `cypress/screenshots` by default. diff --git a/source/guides/references/configuration.md b/source/guides/references/configuration.md index 942a19f6b6..277997bfd1 100644 --- a/source/guides/references/configuration.md +++ b/source/guides/references/configuration.md @@ -57,6 +57,7 @@ Option | Default | Description Option | Default | Description ----- | ---- | ---- +`screenshotOnRunFailure` | `true` | Whether Cypress will take a screenshot when a test fails during `cypress run`. `screenshotsFolder` | `cypress/screenshots` | Path to folder where screenshots will be saved from {% url `cy.screenshot()` screenshot %} command or after a test fails during `cypress run` `trashAssetsBeforeRuns` | `true` | Whether Cypress will trash assets within the `screenshotsFolder` and `videosFolder` before tests run with `cypress run`. diff --git a/source/guides/references/error-messages.md b/source/guides/references/error-messages.md index 67f233ef7f..6a4de62e61 100644 --- a/source/guides/references/error-messages.md +++ b/source/guides/references/error-messages.md @@ -188,6 +188,10 @@ When we say *guard*, this usually means: - Writing an assertion - Waiting on an XHR +### More info + +Read the blog post {% url "Do Not Get Too Detached" https://www.cypress.io/blog/2020/07/22/do-not-get-too-detached/ %} for another example of this error, and how to solve it. + ## {% fa fa-exclamation-triangle red %} `cy....()` failed because the element cannot be interacted with You may see a variation of this message for 4 different reasons: