docs: cy.then and cy.spread usage, requirements, assertions, timeouts

docs/lib/tags/requirements.js

@@ -98,6 +98,13 @@ module.exports = function yields (hexo, args) {
     </ul>`
   }
 
+  const spread = () => {
+    return `<ul>
+      <li><p>${childCmd}.</p></li>
+      <li><p>${cmd} requires being chained off of a command that yields an array-like structure.</p></li>
+    </ul>`
+  }
+
   const exec = () => {
     return `<ul>
       <li><p>${parentCmd}.</p></li>
@@ -170,6 +177,8 @@ module.exports = function yields (hexo, args) {
       return selectability()
     case 'submitability':
       return submitability()
+    case 'spread':
+      return spread()
     case 'exec':
       return exec()
     case 'read_file':

docs/lib/tags/timeouts.js

@@ -90,6 +90,12 @@ module.exports = function yields (hexo, args) {
     </ul>`
   }
 
+  const promises = () => {
+    return `<ul>
+      <li><p>${cmd} can time out waiting for a promise you've returned to resolve.</p></li>
+    </ul>`
+  }
+
   const timeouts = () => {
     return `<ul>
     <li><p>${cmd} will continue to retry its specified assertions until it times out.</p></li>
@@ -117,6 +123,8 @@ module.exports = function yields (hexo, args) {
       return request()
     case 'wait':
       return wait()
+    case 'promises':
+      return promises()
     case 'timeouts':
       return timeouts()
     default:

docs/source/api/commands/spread.md

@@ -6,7 +6,7 @@ comments: false
 Expand an array into multiple arguments.
 
 {% note info %}
-Similar to {% url `.then()` then %}, but always expects an array as it's subject.
+Identical to {% url `.then()` then %}, but always expects an array-like structure as it's subject.
 {% endnote %}
 
 # Syntax
@@ -18,8 +18,6 @@ Similar to {% url `.then()` then %}, but always expects an array as it's subject
 
 ## Usage
 
-`.spread()` requires being chained off another cy command that *yields* an array.
-
 **{% fa fa-check-circle green %} Correct Usage**
 
 ```javascript
@@ -51,8 +49,6 @@ Option | Default | Description
 
 {% yields maybe_changes_subject .spread 'yields the return value of your callback function' %}
 
-## Timeouts {% helper_icon timeout %}
-
 # Examples
 
 ## Aliased Routes
@@ -80,13 +76,25 @@ cy.getCookies().spread(function(cookie1, cookie2, cookie3){
 })
 ```
 
+# Rules
+
+## Requirements {% helper_icon requirements %}
+
+{% requirements spread .spread %}
+
+## Assertions {% helper_icon assertions %}
+
+{% assertions once .spread %}
+
+## Timeouts {% helper_icon timeout %}
+
+{% timeouts promises .spread %}
+
 # Command Log
 
-**`spread` does *not* log in the command log**
+`.spread()` does *not* log in the command log
 
 # See also
 
 - {% url `.each()` each %}
-- {% url `cy.getCookies()` getcookies %}
 - {% url `.then()` then %}
-- {% url `cy.wait()` wait %}

docs/source/api/commands/then.md

@@ -3,7 +3,7 @@ title: then
 comments: false
 ---
 
-Yield the previously yielded subject as the first argument of a function.
+Enables you to work with the subject yielded from the previous command.
 
 # Syntax
 
@@ -14,12 +14,10 @@ Yield the previously yielded subject as the first argument of a function.
 
 ## Usage
 
-`.then()` should be chained off another cy command.
-
 **{% fa fa-check-circle green %} Correct Usage**
 
 ```javascript
-cy.get('.nav').then(function(nav) {})  // Yields .nav as first arg
+cy.get('.nav').then(function($nav) {})  // Yields .nav as first arg
 cy.location().then(function(loc) {})   // Yields location object as first arg
 ```
 
@@ -45,10 +43,6 @@ When `null` or `undefined` are returned by the callback function, the subject wi
 
 Just like Promises, you can return any compatible "thenable" (anything that has a `.then()` interface) and Cypress will wait for that to resolve before continuing forward through the chain of commands.
 
-## Timeouts {% helper_icon timeout %}
-
-`.then()` will retry for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's [options](#options).
-
 # Examples
 
 ## Work with DOM element
@@ -68,9 +62,10 @@ cy.get('form').find('input').then(function($input){
 ```javascript
 cy.then(function(){
   return {id: 123}
-}).then(function(obj){
+})
+.then(function(obj){
   // subject is now the obj {id: 123}
-  obj.id === 123 // true
+  expect(obj.id).to.eq(123) // true
 })
 ```
 
@@ -82,7 +77,8 @@ cy
     console.log('form is:', $form)
     // undefined is returned here, but $form will be
     // yielded to allow for continued chaining
-  }).find('input').then(function($input){
+  })
+  .find('input').then(function($input){
     // we have our $input element here since
     // our form element was yielded and we called
     // .find('input') on it
@@ -101,7 +97,7 @@ cy.get('button').click().then(function($button){
 
   setTimeout(function(){
     p.resolve()
-  }, 5000)
+  }, 1000)
 
   return p.promise
 })
@@ -111,7 +107,7 @@ cy.get('button').click().then(function($button){
 
 ```javascript
 cy.get('button').click().then(function($button){
-  return Promise.delay(5000)
+  return Promise.delay(1000)
 })
 ```
 
@@ -123,7 +119,7 @@ cy.get('button').click().then(function($button){
 
   setTimeout(function(){
     df.resolve()
-  }, 5000)
+  }, 1000)
 
   return df
 })
@@ -133,6 +129,20 @@ cy.get('button').click().then(function($button){
 
 {% partial then_should_difference %}
 
+# Rules
+
+## Requirements {% helper_icon requirements %}
+
+{% requirements child .then %}
+
+## Assertions {% helper_icon assertions %}
+
+{% assertions once .then %}
+
+## Timeouts {% helper_icon timeout %}
+
+{% timeouts promises .then %}
+
 # Command Log
 
 **`cy.then()` does *not* log in the command log**
@@ -142,7 +152,7 @@ cy.get('button').click().then(function($button){
 - {% url `.and()` and %}
 - {% url `.each()` each %}
 - {% url `.invoke()` invoke %}
-- {% url 'Chains of Commands' introduction-to-cypress#Chains-of-Commands %}
 - {% url `.its()` its %}
 - {% url `.should()` should %}
 - {% url `.spread()` spread %}
+- {% url 'Guide: Chains of Commands' introduction-to-cypress#Chains-of-Commands %}