fix: Explain error thrown when cypress commands in .should() callback (#4755)

* fix: Explain error thrown when cypress commands in .should() callback

* Improve layout of previous changes and provide second example of how to fix

* Update content/api/commands/should.md

Co-authored-by: Rachel <[email protected]>

* Apply suggestions from code review

Co-authored-by: Zach Bloomquist <[email protected]>

* Run prettier

* Run prettier again...?

* One more prettier run... :/

Co-authored-by: Rachel <[email protected]>
Co-authored-by: Zach Bloomquist <[email protected]>

Author: 3 people

content/api/commands/should.md

@@ -172,6 +172,35 @@ Be sure _not_ to include any code that has side effects in your callback
 function. The callback function will be retried over and over again until no
 assertions within it throw.
 
+You cannot invoke Cypress commands inside of a `.should()` callback function.
+Use Cypress commands before or after `.should()` instead.
+
+**<Icon name="exclamation-triangle" color="red"></Icon> Incorrect Usage**
+
+```javascript
+cy.get('p').should(($p) => {
+  cy.log($p)
+  // ...
+})
+```
+
+**<Icon name="check-circle" color="green"></Icon> Correct Usage**
+
+```javascript
+cy.get('p')
+  .should(($p) => {
+    // ...
+  })
+  .log()
+
+// or
+
+cy.get('p').then(($p) => {
+  // ...
+  cy.log($p)
+})
+```
+
 #### Verify length, content, and classes from multiple `<p>`
 
 ```html
@@ -467,10 +496,11 @@ following:
 
 ## History
 
-| Version                                       | Changes                           |
-| --------------------------------------------- | --------------------------------- |
-| [0.11.4](/guides/references/changelog#0-11-4) | Allows callback function argument |
-| [< 0.3.3](/guides/references/changelog#0-3-3) | `.should()` command added         |
+| Version                                       | Changes                                         |
+| --------------------------------------------- | ----------------------------------------------- |
+| [11.0.0](/guides/references/changelog#11-0-0) | Throw error if Cypress command used in callback |
+| [0.11.4](/guides/references/changelog#0-11-4) | Allows callback function argument               |
+| [< 0.3.3](/guides/references/changelog#0-3-3) | `.should()` command added                       |
 
 ## See also