BREAKING: 13.0 Docs

docs/api/commands/screenshot.mdx

@@ -278,8 +278,8 @@ Another potential problem to be aware of is that our own Command Log is using
 React under the hood and only rendering asynchronously during an animation
 frame. It is possible you will see screenshots taken before our Command Log is
 done rendering. This means you may not see the **error displayed** in the
-screenshot. But this is also why we take a video - to show you the complete
-failure.
+screenshot. But this is also why we allow taking a video - to show you the
+complete failure.
 
 We make our best effort to synchronize taking a screenshot with our renderer,
 but the current state of your application under test could have changed in the

docs/api/commands/readfile.mdx → docs/api/queries/readfile.mdx

@@ -1,5 +1,6 @@
 ---
 title: readFile
+slug: /api/commands/readfile
 ---
 
 Read a file and yield its contents.
@@ -62,8 +63,8 @@ Pass in an options object to change the default behavior of `cy.readFile()`.
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
 - `cy.readFile()` yields the contents of the file.
-- The file will not be read from disk again if the results are stored in an
-  alias.
+- The file will be read from disk again if any upcoming command (such as an
+  assertion) in the chain fails.
 
 ## Examples
 
@@ -195,6 +196,15 @@ assertions.
 cy.readFile('some/nested/path/story.txt').should('eq', 'Once upon a time...')
 ```
 
+Starting in Cypress 13, `cy.readFile()` is a query, and will continue to read
+the file until all chained commands of any type pass, not just assertions.
+
+```javascript
+// will retry until the json file has a `users[123].name` field, and
+// the assertion passes
+cy.readFile('users.json').its('users.123.name').should('eq', 'John Doe')
+```
+
 ## Rules
 
 ### Requirements [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Chains-of-Commands)
@@ -247,6 +257,7 @@ outputs the following:
 
 | Version                                       | Changes                                   |
 | --------------------------------------------- | ----------------------------------------- |
+| [13.0.0](/guides/references/changelog#13-0-0) | `cy.readFile()` became a query            |
 | [9.0.0](/guides/references/changelog#9-0-0)   | Changed `null` encoding to read as Buffer |
 | [0.17.2](/guides/references/changelog#0-17-2) | Improved error messaging                  |
 | [0.17.1](/guides/references/changelog#0-17-1) | `cy.readFile()` command added             |
@@ -255,5 +266,6 @@ outputs the following:
 
 - [`cy.exec()`](/api/commands/exec)
 - [`cy.fixture()`](/api/commands/fixture) for a similar command with caching
+  that does not retry
 - [`cy.task()`](/api/commands/task)
 - [`cy.writeFile()`](/api/commands/writefile)

docs/guides/continuous-integration/introduction.mdx

@@ -170,7 +170,8 @@ insight into what happened when your tests ran.
 - Get the entire stack trace of failed tests.
 - View screenshots taken when tests fail and when using
   [`cy.screenshot()`](/api/commands/screenshot).
-- Watch a video of your entire test run or a clip at the point of test failure.
+- Watch a video of your entire test run or a clip at the point of test failure
+  when the `video` configuration is enabled.
 - See which machines ran each test when
   [parallelized](/guides/cloud/smart-orchestration/parallelization).
 
@@ -376,6 +377,7 @@ values in the Cypress configuration.
 **_Typical use cases would be modifying things like:_**
 
 - `CYPRESS_BASE_URL`
+- `CYPRESS_VIDEO`
 - `CYPRESS_VIDEO_COMPRESSION`
 - `CYPRESS_REPORTER`
 - `CYPRESS_INSTALL_BINARY`

docs/guides/end-to-end-testing/migration/protractor-to-cypress.mdx

@@ -157,8 +157,8 @@ the failure.
 
 Cypress assists with debugging in headless mode, by automatically taking a
 screenshot of the app UI and command log at the exact point of test failure. To
-help see everything that happened prior to test failure, Cypress provides a
-video recording (as an MP4 file) of a full test spec run by default.
+see everything that happened prior to test failure, enable the `video`
+configuration option to record (as an MP4 file) the full test spec run.
 
 ### Test Retries
 

docs/guides/guides/module-api.mdx

@@ -188,7 +188,6 @@ tests results. A typical run could return something like this:
     }],
     "reporter": "spec",
     "reporterStats": {...},
-    "shouldUploadVideo": true,
     "spec": {...},
     "stats": {
       "suites": 1,

docs/guides/guides/screenshots-and-videos.mdx

@@ -43,75 +43,90 @@ to clear your screenshots folder before a run, you can set
 
 ## Videos
 
-Cypress records a video for each spec file when running tests during
-`cypress run`. Videos are _not_ automatically recorded during `cypress open`.
-
-Video recording can be turned off entirely by setting
-[`video`](/guides/references/configuration#Videos) to `false` from within your
+Video recording is disabled by default, but can be turned on by setting
+[`video`](/guides/references/configuration#Videos) to `true` from within your
 configuration.
 
+If enabled, Cypress records a video for each spec file when running tests during
+`cypress run`. Videos are _not_ recorded during `cypress open`.
+
+:::cypress-config-example
+
+```ts
+{
+  video: true
+}
+```
+
+:::cypress-config-example
+
 Videos are stored in the
 [`videosFolder`](/guides/references/configuration#Videos) which is set to
 `cypress/videos` by default.
 
-After `cypress run` completes, Cypress automatically compresses the video in
-order to save on file size. By default it compresses to a `32 CRF`, but this is
-configurable with the
-[`videoCompression`](/guides/references/configuration#Videos) property.
-
 When using the `--record` flag while running your tests, videos are processed,
 compressed, and uploaded to [Cypress Cloud](/guides/cloud/introduction) after
 every spec file runs, successful or not. To change this behavior to only process
-videos in the case that tests fail, set the
-[`videoUploadOnPasses`](/guides/references/configuration#Videos) configuration
-option to `false`.
+videos in the case that tests fail, see how to
+[delete videos for specs without failing or retried tests](/guides/guides/screenshots-and-videos#Delete-videos-for-specs-without-failing-or-retried-tests).
+Deleting the video will cause the video to not be uploaded to Cypress Cloud.
 
 Cypress clears any existing videos before a `cypress run`. If you do not want to
 clear your videos folder before a run, you can set
 [`trashAssetsBeforeRuns`](/guides/references/configuration#Videos) to `false`.
 
 ### Video encoding
 
-If your spec files have a long run duration, you might notice a time gap between
-a finished spec and a new spec starting during `cypress run`. During this time,
-Cypress is encoding the captured video and possibly uploading it to Cypress
-Cloud.
+After a video is recorded, Cypress encodes the video to a commonly digestable
+format. Part of this encoding process includes video compression.
 
-If the machine is encoding the video slowly (which is often the case for virtual
-machines that use less CPU cores), the encoding might take a long time. In this
-case, you can modify the
-[`videoCompression`](/guides/references/configuration#Videos) configuration to
-make the encoding a little bit faster. Here are some common scenarios:
+Compression is disabled by default, meaning this step will be skipped
+completely, so the file size of the video will be larger, but the encoding
+process is faster. Setting
+[`videoCompression`](/guides/references/configuration#Videos) to `true` will
+coerce the video compression value to 32 Constant Rate Factor (CRF), which takes
+longer to process, but results in a smaller video.
 
-**Change compression value**
+**Enabling compression**
 
 :::cypress-config-example
 
 ```ts
 {
-  videoCompression: 15
+  videoCompression: true
 }
 ```
 
 :::cypress-config-example
 
-A lower `videoCompression` value will spend less time compressing and result in
-a bigger video file size.
+If your spec files have a long run duration and
+[`videoCompression`](/guides/references/configuration#Videos) is enabled, you
+might notice a time gap between a finished spec and a new spec starting during
+`cypress run`. During this time, Cypress is encoding the captured video and
+possibly uploading it to Cypress Cloud.
 
-**Disable compression**
+**Change compression value from 32**
 
 :::cypress-config-example
 
 ```ts
 {
-  videoCompression: false
+  videoCompression: 15
 }
 ```
 
-:::
+:::cypress-config-example
+
+In addition to enabling or disabling video compress, you can specify the CRF
+value used to compress the video. Here is some common scenario:
+
+- If the machine is encoding the video slowly (which is often the case for
+  virtual machines that use less CPU cores), try increasing the CRF value.
 
-The compression step will be skipped completely, so the video will be large, but
-the processing should be faster.
+- If your videos are extremely low quality, try decreasing the CRF value.
+
+A lower `videoCompression` value will spend less time compressing and result in
+a bigger video file size and higher quality video.
 
 :::info
 
@@ -128,9 +143,9 @@ to Cypress Cloud. Deleting videos after the run can save resource space on the
 machine as well as skip the time used to process, compress, and upload the video
 to [Cypress Cloud](/guides/cloud/introduction).
 
-To only process videos in the case that a test fails, you can set the
-[`videoUploadOnPasses`](/guides/references/configuration#Videos) configuration
-option to `false`.
+To only process videos in the case that a test fails, you can
+[delete videos for specs without failing or retried tests](/guides/guides/screenshots-and-videos#Delete-videos-for-specs-without-failing-or-retried-tests),
+which will not upload the video of passed runs to Cypress Cloud.
 
 For more fine grained control, you can use Cypress's
 [`after:spec`](/api/plugins/after-spec-api) event listener that fires after each

docs/guides/overview/why-cypress.mdx

@@ -117,9 +117,9 @@ do that no other testing framework can:
 - **Consistent Results:** Our architecture doesn't use Selenium or WebDriver.
   Say hello to fast, consistent and reliable tests that are flake-free.
 - **Screenshots and Videos:** View screenshots taken automatically on failure,
-  or videos of your entire test suite when run from the CLI. Record to
-  [Cypress Cloud](/guides/cloud/introduction) to store them with your test
-  results for zero-configuration debugging.
+  or videos, if enabled, of your entire test suite when run from the CLI. Record
+  to [Cypress Cloud](/guides/cloud/introduction) to store them with your test
+  results.
 - **Cross Browser Testing:** Run tests within Firefox and Chrome-family browsers
   (including Edge and Electron) locally and
   [optimally in a Continuous Integration pipeline](/guides/guides/cross-browser-testing).

docs/guides/references/configuration.mdx

@@ -124,10 +124,9 @@ For more options regarding screenshots, view the
 | Option                  | Default          | Description                                                                                                                                                                                                                                                                                                              |
 | ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `trashAssetsBeforeRuns` | `true`           | Whether Cypress will trash assets within the `downloadsFolder`, `screenshotsFolder`, and `videosFolder` before tests run with `cypress run`.                                                                                                                                                                             |
-| `videoCompression`      | `32`             | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size).                                                                     |
+| `videoCompression`      | `false`          | The quality setting for the video compression, in Constant Rate Factor (CRF). The value can be `false` to disable compression or a value between `0` and `51`, where a lower value results in better quality (at the expense of a higher file size).                                                                     |
 | `videosFolder`          | `cypress/videos` | Where Cypress will automatically save the video of the test run when tests run with `cypress run`.                                                                                                                                                                                                                       |
-| `video`                 | `true`           | Whether Cypress will capture a video of the tests run with `cypress run`.                                                                                                                                                                                                                                                |
-| `videoUploadOnPasses`   | `true`           | Whether Cypress will process, compress, and upload videos to [Cypress Cloud](/guides/cloud/introduction) even when all tests in a spec file are passing. This only applies when recording your runs to Cypress Cloud. Turn this off if you'd like to only upload the spec file's video when there are failing tests. |
+| `video`                 | `false`          | Whether Cypress will capture a video of the tests run with `cypress run`.                                                                                                                                                                                                                                                |
 
 ### Downloads
 
@@ -741,6 +740,7 @@ DEBUG=cypress:cli,cypress:server:specs
 
 | Version                                       | Changes                                                                               |
 | --------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [13.0.0](/guides/references/changelog#13-0-0) | Removed `videoUploadOnPasses` option.                                                 |
 | [11.0.0](/guides/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option.                                    |
 | [10.4.0](/guides/references/changelog#10-4-0) | Added `e2e.testIsolation` option.                                                     |
 | [10.0.0](/guides/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. |

docs/guides/references/migration-guide.mdx

@@ -2,6 +2,68 @@
 title: Migration Guide
 ---
 
+## Migrating to Cypress 13.0
+
+This guide details the changes and how to change your code to migrate to Cypress
+version 13.0.
+[See the full changelog for version 12.0](/guides/references/changelog#12-0-0).
+
+### `cy.readFile()` is now a query command
+
+In Cypress 13, the [`.readFile()`](/api/commands/as) command is now a query.
+Tests written using it should continue to operate exactly as before; no changes
+are necessary.
+
+This means that `readFile()` will re-read the file from disk if any upcoming
+command in the same chain fails. Assertions no longer have to be directly
+attached.
+
+```js
+cy.readFile(`users.json`).its('users.123.fullName').should('eq', 'John Doe')
+```
+
+Beginning with Cypress 13, the above test will re-read the file until the file
+exists, it has the requested property, and it passes the assertion.
+
+In previous versions of Cypress, the above command would retry until the file
+existed, but would _not_ re-read it from disk if the file didn't have the
+requested property or the contents didn't match.
+
+#### `.readFile()` can no longer be overwritten with `Cypress.Commands.overwrite()`
+
+However, queries cannot be overwritten using `Cypress.Commands.overwrite()`. If
+you were previously overwriting `cy.readFile()`, you will need to put your
+custom version under a new name, and update your tests to use it. For example,
+you might update this test:
+
+```js
+Cypress.Commands.override('readFile', (originalFn, fileName, options) => {
+  originalFn(fileName, options).then((file) => {
+    // Do some processing
+    return updatedFile
+  })
+})
+
+it('reads a file', () => {
+  cy.readFile('foo.json')
+})
+```
+
+to something like this:
+
+```js
+Cypress.Commands.create('readFileWithExtras', (fileName, options) => {
+  cy.readFile(fileName, options).then((file) => {
+    // Do some processing
+    return updatedFile
+  })
+})
+
+it('reads a file', () => {
+  cy.readFileWithExtras('foo.json')
+})
+```
+
 ## Migrating to Cypress 12.0
 
 This guide details the changes and how to change your code to migrate to Cypress