.readFile() is now a query (#5017)

* .readFile() is now a query

* Add section on new .readFile() superpowers

* Fix page slug for readFile

* Prettier run

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