docs: WIP lots more requirements, timeouts, content updates

docs/lib/tags/requirements.js

@@ -86,6 +86,15 @@ module.exports = function yields (hexo, args) {
     </ul>`
   }
 
+  const page = () => {
+    return render(`<ul>
+      <li><p>${cmd} requires the response to be <code>content-type: text/html</code>.</p></li>
+      <li><p>${cmd} requires the response code to be <code>2xx</code> after following redirects.</p></li>
+      <li><p>${cmd} requires the load <code>load</code> event to eventually fire.</p></li>
+      <li><p>${actionable}.</p></li>
+    </ul>`)
+  }
+
   switch (type) {
     case 'none':
       return none()
@@ -107,6 +116,8 @@ module.exports = function yields (hexo, args) {
       return readFile()
     case 'write_file':
       return writeFile()
+    case 'page':
+      return page()
     default:
       // error when an invalid usage option was provided
       throw new Error(`{% requirements %} tag helper was provided an invalid option: ${type}`)

docs/lib/tags/timeouts.js

@@ -63,6 +63,13 @@ module.exports = function yields (hexo, args) {
     </ul>`
   }
 
+  const page = () => {
+    return `<ul>
+    <li><p>${cmd} can time out waiting for the page to fire its <code>load</code> event.</p></li>
+    <li><p>${assertion}.</p></li>
+    </ul>`
+  }
+
   switch (type) {
     case 'assertions':
       return assertions()
@@ -76,6 +83,8 @@ module.exports = function yields (hexo, args) {
       return exec()
     case 'none':
       return none()
+    case 'page':
+      return page()
     default:
       // error when an invalid usage option was provided
       throw new Error(`{% timeouts %} tag helper was provided an invalid option: ${type}`)

docs/source/api/commands/_scrollintoview.md

@@ -48,9 +48,13 @@ Option | Default | Description
 
 {% yields same_subject .scrollIntoView %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none .scrollToIntoView %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`.scrollIntoView()` will continue to scroll the element into view for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %}.
+{% timeouts assertions .scrollToIntoView %}
 
 # Examples
 

docs/source/api/commands/_scrollto.md

@@ -64,6 +64,14 @@ Option | Default | Description
 
 `cy.scrollTo()` will wait until the window or element is in a 'scrollable' state for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's options.
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements scrollability .scrollTo %}
+
+## Timeouts {% helper_icon timeout %}
+
+{% timeouts assertions .scrollTo %}
+
 # Examples
 
 ## Position

docs/source/api/commands/_trigger.md

@@ -60,6 +60,7 @@ Pass in an options object to change the default behavior of `.trigger()`.
 Option | Default | Description
 --- | --- | ---
 `log` | `true` | {% usage_options log %}
+`force` | `false` | {% usage_options force trigger %}
 `bubbles` | `true` | Whether the event bubbles
 `cancelable` | `true` | Whether the event is cancelable
 `timeout` | {% url `defaultCommandTimeout` configuration#Timeouts %} | {% usage_options timeout .trigger %}
@@ -70,9 +71,13 @@ You can also include arbitrary event properties (e.g. `clientX`, `shiftKey`) and
 
 {% yields same_subject .trigger %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements actionability .trigger %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`.trigger()` will wait until the element is in an 'interactable' state for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's options.
+{% timeouts actionability .trigger %}
 
 # Examples
 

docs/source/api/commands/go.md

@@ -44,9 +44,13 @@ Option | Default | Description
 
 {% yields new_subject cy.go 'yields the `window` object after the page finishes loading' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements page cy.go %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.go()` will retry for the duration of the {% url `pageLoadTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's options.
+{% timeouts page cy.go %}
 
 # Examples
 

docs/source/api/commands/hash.md

@@ -49,8 +49,14 @@ Option | Default | Description
 
 {% yields new_subject cy.hash "yields an empty string" %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.hash %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts assertions cy.hash %}
+
 # Examples
 
 ## Hash

docs/source/api/commands/location.md

@@ -54,8 +54,14 @@ Option | Default | Description
 - `search`
 - `toString`
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.location %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts assertions cy.location %}
+
 # Examples
 
 ## Location Properties

docs/source/api/commands/reload.md

@@ -41,9 +41,13 @@ Option | Default | Description
 
 {% yields new_subject cy.reload 'yields the `window` object after the page finishes loading' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements page cy.reload %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.reload()` will wait for the load event of the newly loaded page for the duration of the {% url `pageLoadTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's options.
+{% timeouts page cy.reload %}
 
 # Examples
 
@@ -86,5 +90,4 @@ When clicking on `reload` within the command log, the console outputs the follow
 # See also
 
 - {% url `cy.go()` go %}
-- {% url `cy.location()` location %}
 - {% url `cy.visit()` visit %}

docs/source/api/commands/root.md

@@ -42,9 +42,13 @@ Option | Default | Description
 
 The root element yielded is `document` by default. However, when calling `.root()` from within the callback function of a {% url `.within()` within %} command, the root element yielded is the yielded subject of the {% url `.within()` within %} command.
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.root %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`.root()` will continue to look for the root element for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %}.
+{% timeouts assertions cy.root %}
 
 # Examples
 

docs/source/api/commands/route.md

@@ -71,8 +71,14 @@ You can also set options for all {% url `cy.wait()` wait %}'s `requestTimeout` a
 
 {% yields null cy.route %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.route %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none cy.route %}
+
 # Examples
 
 ## Non-stubbed requests

docs/source/api/commands/screenshot.md

@@ -43,9 +43,13 @@ Option | Default | Description
 
 {% yields null cy.screenshot %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.screenshot %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.screenshot()` will wait up for the duration of {% url `responseTimeout` configuration#Timeouts %} for the automation server to process this command.
+{% timeouts automation cy.screenshot %}
 
 # Examples
 

docs/source/api/commands/server.md

@@ -63,8 +63,13 @@ Option | Default | Description
 
 {% yields new_subject cy.server 'yields the internal Cypress server instance' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.server %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none cy.server %}
 
 # Examples
 

docs/source/api/commands/spy.md

@@ -41,8 +41,14 @@ Unlike most Cypress commands, `cy.spy()` is *synchronous* and returns a value (t
 
 `cy.spy()` returns a [Sinon.js spy](http://sinonjs.org/docs/#spies). All [methods](http://sinonjs.org/docs/#spies-api) found on Sinon.JS spies are supported.
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.spy %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none cy.spy %}
+
 # Examples
 
 ## Spy

docs/source/api/commands/stub.md

@@ -47,8 +47,12 @@ Unlike most Cypress commands, `cy.stub()` is *synchronous* and returns a value (
 
 `cy.stub()` returns a {% url "Sinon.js stub" http://sinonjs.org/%}. All methods found on {% url "Sinon.js" http://sinonjs.org %} spies and stubs are supported.
 
+{% requirements none cy.stub %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none cy.stub %}
+
 # Examples
 
 ## Stub

docs/source/api/commands/title.md

@@ -37,9 +37,13 @@ Option | Default | Description
 
 {% yields new_subject cy.title 'yields the `document.title` of the current page' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.title %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.title()` will continue to retry for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %}
+{% timeouts assertions cy.title %}
 
 # Examples
 

docs/source/api/commands/url.md

@@ -43,8 +43,14 @@ Option | Default | Description
 
 {% yields new_subject cy.url 'yields the current URL as a string' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.url %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts assertions cy.url %}
+
 # Examples
 
 ## Url

docs/source/api/commands/viewport.md

@@ -72,8 +72,14 @@ Option | Default | Description
 
 {% yields null cy.viewport %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.viewport %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none cy.viewport %}
+
 # Examples
 
 ## Width, Height

docs/source/api/commands/visit.md

@@ -45,9 +45,13 @@ You can also set all `cy.visit()` commands' `pageLoadTimeout` and `baseUrl` glob
 
 {% yields new_subject cy.visit 'yields the `window` object after the page finishes loading' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements page cy.visit %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.visit()` will retry for the duration of the {% url `pageLoadTimeout` configuration#Timeouts %} or the duration of the `timeout` specified in the command's [options](#options).
+{% timeouts page cy.visit %}
 
 # Examples
 
@@ -206,7 +210,7 @@ When clicking on `visit` within the command log, the console outputs the followi
 # See also
 
 - {% url `cy.go()` go %}
+- {% url `cy.reload()` reload %}
+- {% url `cy.request()` request %}
 - {% url "Recipe: Bootstrapping App Test Data" working-with-the-backend %}
 - {% url "Recipe: Logging In - Single Sign on" logging-in %}
-- {% url `cy.request()` request %}
-- {% url `cy.server()` server %}

docs/source/api/commands/window.md

@@ -3,7 +3,7 @@ title: window
 comments: false
 ---
 
-Get the global `window` object of the remote application that was visited in {% url `cy.visit()` visit %}.
+Get the global `window` object of the page that was visited in {% url `cy.visit()` visit %}.
 
 # Syntax
 
@@ -37,9 +37,13 @@ Option | Default | Description
 
 {% yields new_subject cy.window 'yields the `window` object' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.window %}
+
 ## Timeouts {% helper_icon timeout %}
 
-`cy.window()` will retry for the duration of the {% url `defaultCommandTimeout` configuration#Timeouts %}.
+{% timeouts assertions cy.window %}
 
 # Examples
 

docs/source/api/commands/within.md

@@ -2,8 +2,7 @@
 title: within
 comments: false
 ---
-
-Set the scope of the containing commands to the previously yielded subject and pass that as an argument to the callback function.
+Scopes all subsequent cy commands to within this element. Useful when working within a particular group of elements such as a `<form>`.
 
 # Syntax
 
@@ -47,8 +46,14 @@ Option | Default | Description
 
 {% yields same_subject .within %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none .within %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts none .within %}
+
 # Examples
 
 ## Within

docs/source/api/commands/wrap.md

@@ -41,8 +41,14 @@ Option | Default | Description
 
 {% yields new_subject cy.wrap 'yields the object it was called with' %}
 
+## Requirements {% helper_icon defaultAssertion %}
+
+{% requirements none cy.wrap %}
+
 ## Timeouts {% helper_icon timeout %}
 
+{% timeouts assertions cy.wrap %}
+
 # Examples
 
 ## Wrap