fix: update retry ability guide and migration guide now that should() and and() will not be queries in v13. see cypress-io/cypress#25738

Author: AtofStryker

docs/guides/core-concepts/retry-ability.mdx

@@ -37,15 +37,15 @@ important to understand the different rules by which they operate.
   log.
 - **Non-queries** only execute once.
 
-For example, there are 7 queries (2 of them assertions) and 2 non-queries in the
-test below.
+For example, there are 4 queries, an action, and 2 assertions in
+the test below.
 
 ```javascript
 it('creates an item', () => {
   // Non-query commands only execute once.
   cy.visit('/')
 
-  // The queries .focused() and .should() link together,
+  // The .focused() query and .should() assertion link together, 
   // rerunning until the currently focused element has
   // the 'new-todo' class
   cy.focused().should('have.class', 'new-todo')
@@ -55,7 +55,7 @@ it('creates an item', () => {
   // the non-query `.type()`.
   cy.get('.header').find('.new-todo').type('todo A{enter}')
 
-  // Three queries chained together
+  // Two queries and an assertion chained together
   cy.get('.todoapp').find('.todo-list li').should('have.length', 1)
 })
 ```
@@ -136,12 +136,16 @@ Within a few milliseconds after the DOM updates, the linked queries
 
 ## Multiple assertions
 
-Chains of commands are always executed in order, with all previous queries
-forming the subject of each following command.
+Queries and assertions are always executed in order, and always retry 'from the
+top'. If you have multiple assertions, Cypress will retry until each passes
+before moving on to the next one.
 
-For example, the following test has the [.get()](/api/commands/get),
-[`.should()`](/api/commands/should) and [`.and()`](/api/commands/and) commands
-chained together. All three of these are queries.
+For example, the following test has [`.should()`](/api/commands/should) and
+[`.and()`](/api/commands/and) assertions. `.and()` is an alias of the
+`.should()` command, so the second assertion is really a custom callback
+assertion in the form of the [`.should(cb)`](/api/commands/should#Function)
+function with 2 [`expect`](/guides/references/assertions#BDD-Assertions)
+assertions inside of it.
 
 ```javascript
 it('creates two items', () => {
@@ -151,9 +155,9 @@ it('creates two items', () => {
   cy.get('.new-todo').type('todo B{enter}')
 
   cy.get('.todo-list li') // query
-    .should('have.length', 2) // query
+    .should('have.length', 2) // assertion
     .and(($li) => {
-      // 2 mocha assertions inside of the .and() query
+      // 2 mocha assertions inside of the .and() assertion
       expect($li.get(0).textContent, 'first item').to.equal('todo a')
       expect($li.get(1).textContent, 'second item').to.equal('todo B')
     })
@@ -163,7 +167,8 @@ it('creates two items', () => {
 Because the first expect statement
 (`expect($li.get(0).textContent, 'first item').to.equal('todo a')`) fails, the
 second statement is never reached. The `.and()` command fails after timing out,
-and the Command Log correctly shows that `.get()` and `.should()` passed, but
+and the Command Log correctly shows that the first encountered assertion
+`should('have.length', 2)` passed, but
 the "first item" assertion failed.
 
 <DocsImage
@@ -179,7 +184,9 @@ will be retried even without any attached assertions until it finds an element
 with the given index.
 
 ```javascript
-cy.get('.todo-list li').should('have.length', 2).eq(3)
+cy.get('.todo-list li') // query
+  .should('have.length', 2) // assertion
+  .eq(3) // query
 ```
 
 <DocsImage

docs/guides/references/migration-guide.mdx

@@ -6,17 +6,16 @@ title: Migration Guide
 
 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).
+[See the full changelog for version 13.0](/guides/references/changelog#13-0-0).
 
 ### `cy.readFile()` is now a query command
 
-In Cypress 13, the [`.readFile()`](/api/commands/as) command is now a query.
+In Cypress 13, the [`.readFile()`](/api/commands/readFile) 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.
+`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')
@@ -31,38 +30,12 @@ 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')
-})
-```
+Queries must be overwritten using `Cypress.Commands.overwriteQuery()`. If you
+were previously overwriting `cy.readFile()`, you will need to update your code
+to use `Cypress.Commands.overwriteQuery('readFile', function() { ... })` rather
+than `Cypress.Commands.overwrite('readFile', () => { ... })`. For more details
+on overwriting queries, see the
+[Overwriting Existing Queries](/api/cypress-api/custom-queries#Overwriting-Existing-Queries).
 
 ## Migrating to Cypress 12.0