Add screenshotOnRunFailure to configuration option

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.
 

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 `<projectRoot>/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 %}

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/ %}

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.
 

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`.
 

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: