docs: Queries, Detached DOM, and Retry-Ability (#4835)

* First rework of retryability guide

* Update each command's Yields section, and all guides, with information about queries vs commands

* Add Custom Queries page

* Minor formatting tweaks

* Review changes

* Review updates

* Update based on review + last week meetings

* More review updates

* Fix tests

content/api/commands/and.md

@@ -2,8 +2,8 @@
 title: and
 ---
 
-Create an assertion. Assertions are automatically retried until they pass or
-time out.
+Create an assertion. Assertions are automatically retried as part of the
+previous command until they pass or time out.
 
 <Alert type="info">
 
@@ -33,7 +33,9 @@ An alias of [`.should()`](/api/commands/should)
 
 ```javascript
 cy.get('.err').should('be.empty').and('be.hidden') // Assert '.err' is empty & hidden
+
 cy.contains('Login').and('be.visible') // Assert el is visible
+
 cy.wrap({ foo: 'bar' })
   .should('have.property', 'foo') // Assert 'foo' property exists
   .and('eq', 'bar') // Assert 'foo' property is 'bar'
@@ -42,7 +44,10 @@ cy.wrap({ foo: 'bar' })
 **<Icon name="exclamation-triangle" color="red"></Icon> Incorrect Usage**
 
 ```javascript
-cy.and('eq', '42') // Should not be chained off 'cy'
+cy.and('eq', '42') // Can not be chained off 'cy'
+
+cy.get('button').click().and('be.focused') // Should not be chained off
+// action commands that may update the DOM
 ```
 
 ### Arguments
@@ -68,8 +73,9 @@ Whatever was passed to the function is what is yielded.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>In most cases, `.and()` yields the same subject it was given from the
-previous command.</li></List>
+- In most cases, `.and()` yields the same subject it was given.
+- `.and()` is an assertion, and it is _safe_ to chain further commands that use
+  the subject.
 
 ```javascript
 cy.get('nav') // yields <nav>

content/api/commands/as.md

@@ -3,8 +3,8 @@ title: as
 ---
 
 Assign an alias for later use. Reference the alias later within a
-[`cy.get()`](/api/commands/get) or [`cy.wait()`](/api/commands/wait) command
-with an `@` prefix.
+[`cy.get()`](/api/commands/get) query or [`cy.wait()`](/api/commands/wait)
+command with an `@` prefix.
 
 <Alert type="info">
 
@@ -46,8 +46,8 @@ using an `@` prefix.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.as()` yields the same subject it was given from the previous
-command.</li></List>
+- `.as()` yields the same subject it was given.
+- It is _safe_ to chain further commands after `.as()`.
 
 ## Examples
 

content/api/commands/blur.md

@@ -4,12 +4,20 @@ title: blur
 
 Blur a focused element.
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.blur()`.
+
 <Alert type="warning">
 
 This element must currently be in focus. If you want to ensure an element is
 focused before blurring, try using [`.focus()`](/api/commands/focus) before
 `.blur()`.
 
+```javascript
+cy.get('button').as('btn').focus()
+cy.get('@btn').blur()
+```
+
 </Alert>
 
 ## Syntax
@@ -24,8 +32,8 @@ focused before blurring, try using [`.focus()`](/api/commands/focus) before
 **<Icon name="check-circle" color="green"></Icon> Correct Usage**
 
 ```javascript
-cy.get('[type="email"]').type('[email protected]').blur() // Blur email input
-cy.get('[tabindex="1"]').focus().blur() // Blur el with tabindex
+cy.get('[type="email"]').blur() // Blur email input
+cy.get('[tabindex="1"]').blur() // Blur el with tabindex
 ```
 
 **<Icon name="exclamation-triangle" color="red"></Icon> Incorrect Usage**
@@ -49,8 +57,9 @@ Pass in an options object to change the default behavior of `.blur`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.blur()` yields the same subject it was given from the previous
-command.</li></List>
+- `.blur()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.blur()`.
 
 ## Examples
 

content/api/commands/check.md

@@ -4,6 +4,9 @@ title: check
 
 Check checkbox(es) or radio(s).
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.check()`.
+
 <Alert type="warning">
 
 This element must be an `<input>` with type `checkbox` or `radio`.
@@ -62,8 +65,9 @@ Pass in an options object to change the default behavior of `.check()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.check()` yields the same subject it was given from the previous
-command.</li></List>
+- `.check()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.check()`.
 
 ## Examples
 

content/api/commands/children.md

@@ -52,7 +52,8 @@ Pass in an options object to change the default behavior of `.children()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.children()` yields the new DOM element(s) it found.</li></List>
+- `.children()` yields the new DOM element(s) it found.
+- `.children()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/clear.md

@@ -4,6 +4,9 @@ title: clear
 
 Clear the value of an `input` or `textarea`.
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.clear()`.
+
 <Alert type="info">
 
 An alias for [`.type('{selectall}{backspace}')`](/api/commands/type)
@@ -52,8 +55,9 @@ Pass in an options object to change the default behavior of `.clear()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.clear()` yields the same subject it was given from the previous
-command.</li></List>
+- `.clear()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.clear()`.
 
 ## Examples
 

content/api/commands/clearcookie.md

@@ -45,8 +45,7 @@ Pass in an options object to change the default behavior of `cy.clearCookie()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.clearCookie()` yields `null`.</li><li>`cy.clearCookie()` cannot be
-chained further.</li></List>
+- `cy.clearCookie()` yields `null`.
 
 ## Examples
 

content/api/commands/clearcookies.md

@@ -41,8 +41,7 @@ Pass in an options object to change the default behavior of `cy.clearCookies()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.clearCookies()` yields `null`.</li><li>`cy.clearCookies()` cannot
-be chained further.</li></List>
+- `cy.clearCookies()` yields `null`.
 
 ## Examples
 

content/api/commands/clearlocalstorage.md

@@ -46,8 +46,7 @@ Pass in an options object to change the default behavior of
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.clearLocalStorage()` yields
-`null`.</li><li>`cy.clearLocalStorage()` cannot be chained further.</li></List>
+- `cy.clearLocalStorage()` yields `null`.
 
 ## Examples
 

content/api/commands/click.md

@@ -4,6 +4,9 @@ title: click
 
 Click a DOM element.
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.click()`.
+
 ## Syntax
 
 ```javascript
@@ -70,8 +73,9 @@ Pass in an options object to change the default behavior of `.click()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.click()` yields the same subject it was given from the previous
-command.</li></List>
+- `.click()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.click()`.
 
 ## Examples
 

content/api/commands/closest.md

@@ -51,7 +51,8 @@ Pass in an options object to change the default behavior of `.closest()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.closest()` yields the new DOM element(s) it found.</li></List>
+- `.closest()` yields the new DOM element(s) it found.
+- `.closest()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/contains.md

@@ -64,7 +64,8 @@ Pass in an options object to change the default behavior of `.contains()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.contains()` yields the new DOM element it found.</li></List>
+- `.contains()` yields the new DOM element it found.
+- `.contains()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/dblclick.md

@@ -4,6 +4,9 @@ title: dblclick
 
 Double-click a DOM element.
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.dblclick()`.
+
 ## Syntax
 
 ```javascript
@@ -70,8 +73,9 @@ Pass in an options object to change the default behavior of `.dblclick()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.dblclick()` yields the same subject it was given from the previous
-command.</li></List>
+- `.dblclick()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.dblclick()`.
 
 ## Examples
 

content/api/commands/debug.md

@@ -43,8 +43,8 @@ Pass in an options object to change the default behavior of `.debug()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.debug()` yields the same subject it was given from the previous
-command.</li></List>
+- `.debug()` yields the same subject it was given from the previous command.
+- `.debug()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/document.md

@@ -32,7 +32,8 @@ Pass in an options object to change the default behavior of `cy.document()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`cy.document()` 'yields the `window.document` object' </li></List>
+- `cy.document()` 'yields the `window.document` object.
+- `cy.document()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/each.md

@@ -5,6 +5,9 @@ title: each
 Iterate through an array like structure (arrays or objects with a `length`
 property).
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.each()`.
+
 ## Syntax
 
 ```javascript
@@ -40,8 +43,9 @@ Pass a function that is invoked with the following arguments:
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.each()` yields the same subject it was given from the previous
-command.</li></List>
+- `.each()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.each()`.
 
 ## Examples
 

content/api/commands/end.md

@@ -21,13 +21,12 @@ cy.contains('ul').end() // Yield 'null' instead of 'ul' element
 **<Icon name="exclamation-triangle" color="red"></Icon> Incorrect Usage**
 
 ```javascript
-cy.end() // Does not make sense to chain off 'cy'
+cy.end()
 ```
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.end()` yields `null`.</li><li>`.end()` cannot be chained
-further.</li></List>
+- `.end()` yields `null`.
 
 ## Examples
 

content/api/commands/eq.md

@@ -59,7 +59,8 @@ Pass in an options object to change the default behavior of `.eq()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.eq()` yields the new DOM element(s) it found.</li></List>
+- `.eq()` yields the new DOM element it found.
+- `.eq()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/filter.md

@@ -56,7 +56,8 @@ Pass in an options object to change the default behavior of `.filter()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.filter()` yields the new DOM element(s) it found.</li></List>
+- `.filter()` yields the new DOM element(s) it found.
+- `.filter()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/find.md

@@ -51,7 +51,8 @@ Pass in an options object to change the default behavior of `.find()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.find()` yields the new DOM element(s) it found.</li></List>
+- `.find()` yields the new DOM element(s) it found.
+- `.find()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/first.md

@@ -46,7 +46,8 @@ Pass in an options object to change the default behavior of `.first()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.first()` yields the new DOM element(s) it found.</li></List>
+- `.first()` yields the new DOM element it found.
+- `.first()` is a query, and it is _safe_ to chain further commands.
 
 ## Examples
 

content/api/commands/fixture.md

@@ -71,8 +71,9 @@ Pass in an options object to change the default behavior of `cy.fixture()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-`cy.fixture()` yields the contents of the file. Formatting is determined by its
-file extension.
+- `cy.fixture()` yields the contents of the file. Formatting is determined by
+  its file extension.
+- The yielded subject is **not** updated if the contents change on disk.
 
 ## Examples
 

content/api/commands/focus.md

@@ -4,6 +4,9 @@ title: focus
 
 Focus on a DOM element.
 
+It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried) to
+chain further commands that rely on the subject after `.focus()`.
+
 ## Syntax
 
 ```javascript
@@ -39,8 +42,9 @@ Pass in an options object to change the default behavior of `.focus()`.
 
 ### Yields [<Icon name="question-circle"/>](/guides/core-concepts/introduction-to-cypress#Subject-Management)
 
-<List><li>`.focus()` yields the same subject it was given from the previous
-command.</li></List>
+- `.focus()` yields the same subject it was given.
+- It is [unsafe](/guides/core-concepts/retry-ability#Only-queries-are-retried)
+  to chain further commands that rely on the subject after `.focus()`.
 
 ## Examples