docs for experimental session API

source/_data/sidebar.yml

@@ -153,6 +153,8 @@ api:
     within: within.html
     wrap: wrap.html
     writefile: writefile.html
+    useSession: useSession.html
+    defineSession: defineSession.html
   utilities:
     _: _.html
     $: $.html

source/api/commands/defineSession.md

@@ -0,0 +1,40 @@
+---
+title: defineSession
+containerClass: experimental
+---
+
+{% note warning %}
+{% fa fa-warning orange %} **This is an experimental feature. In order to use it, you must set the {% url "`experimentalSessionSupport`" experiments %} configuration option to `true`.**
+{% endnote %}
+
+Defines a `Session`. A `Session` a collection of `cookies` and `localStorage` across all domains that may be restored to at any point during a test with the accompanying {% url `cy.useSession()` useSession %} command.
+
+## Usage
+```ts
+cy.defineSession(name, steps, options?)
+cy.defineSession(options)
+```
+
+## Arguments
+
+**{% fa fa-angle-right %} name** ***(String)***
+The name of the `Session` to be referenced later within a {% url `cy.useSession()` useSession %} command.
+
+**{% fa fa-angle-right %} steps** ***(Function)***
+A function containing the Cypress commands needed to set `Session` data. For example, logging into your application.
+
+**{% fa fa-angle-right %} options** ***(Object)***
+
+Option | Default | Description
+--- | --- | ---
+`name` | `null` | The name of the session
+`steps` | `null` | A function containing the Cypress commands for intializing `Session` state
+`after` | `null` | A function that always runs **after** {% url `cy.useSession()` useSession %} for both new and saved `Sessions`. 
+`before` | `null` | A function that always runs **before** {% url `cy.useSession()` useSession %} for both new and saved `Sessions`. 
+`verify` | `null` | A function that, when returns false, invalidates and recreates the session during {% url `cy.useSession()` useSession %}
+
+## Yields {% helper_icon yields %}
+
+Unlike most Cypress commands, `cy.defineSession()` is *synchronous* and returns the `Session` reference instead of a Promise-like chain-able object. This allows you to assign the `Session` object and pass the reference directly to {% url `cy.useSession()` useSession %}. You may also place `cy.defineSession()` calls in a `cypress/support` and export the session objects for use in multiple spec files.
+
+**Note:** You may also ignore the return value and reference the `Session` by name in {% url `cy.useSession()` useSession %}

source/api/commands/getcookie.md

@@ -46,6 +46,7 @@ Option | Default | Description
 - `sameSite` *(if specified)*
 - `secure`
 - `value`
+- `hostOnly` *(if specified)*
 
 ### When a cookie matching the name could not be found:
 

source/api/commands/getcookies.md

@@ -42,6 +42,7 @@ Option | Default | Description
 - `sameSite` *(if specified)*
 - `secure`
 - `value`
+- `hostOnly` *(if specified)*
 
 # Examples
 
@@ -98,6 +99,7 @@ When clicking on `getCookies` within the command log, the console outputs the fo
 {% imgTag /img/api/getcookies/test-application-cookies.png "Console Log getcookies" %}
 
 {% history %}
+{% url "6.3.0" changelog#6-3-0 %} | Added the `hostOnly` property.
 {% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made `sameSite` property always available.
 {% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`.
 {% endhistory %}

source/api/commands/setcookie.md

@@ -39,6 +39,7 @@ Option | Default | Description
 `domain` | `window.location.hostname` | The domain the cookie is visible to
 `expiry` | 20 years into the future | When the cookie expires, specified in seconds since {% url 'Unix Epoch' https://en.wikipedia.org/wiki/Unix_time %}.
 `httpOnly` | `false` | Whether the cookie is an HTTP only cookie
+`hostOnly` | `false` | Whether the cookie should apply only to the supplied domain, not subdomains.
 `path` | `/` | The cookie path
 `secure` | `false` | Whether the cookie is a secure cookie
 `timeout` | {% url `responseTimeout` configuration#Timeouts %} | {% usage_options timeout cy.setCookie %}
@@ -100,6 +101,7 @@ When clicking on `setCookie` within the command log, the console outputs the fol
 {% imgTag /img/api/setcookie/see-cookie-properties-expiry-domain-and-others-in-test.png "Console Log setcookie" %}
 
 {% history %}
+{% url "6.3.0" changelog#6-3-0 %} | Added the `hostOnly` property.
 {% url "5.0.0" changelog#5-0-0 %} | Removed `experimentalGetCookiesSameSite` and made `sameSite` property always available.
 {% url "4.3.0" changelog#4-3-0 %} | Added `sameSite` property when the {% url "`experimentalGetCookiesSameSite`" configuration#Experiments %} configuration value is `true`.
 {% url "0.16.0" changelog#0-16-0 %} | `cy.setCookie()` command added

source/api/commands/useSession.md

@@ -0,0 +1,98 @@
+---
+title: useSession
+containerClass: experimental
+---
+
+{% note warning %}
+{% fa fa-warning orange %} **This is an experimental feature. In order to use it, you must set the {% url "`experimentalSessionSupport`" experiments %} configuration option to `true`.**
+{% endnote %}
+
+
+Use `cy.useSession()` to set client-stored persisted data in your application. A `Session` consists of `cookies` and `localStorage` and is created with the accompanying {% url `cy.defineSession()` defineSession %} command.
+
+With `cy.useSession()`, you can:
+* set `cookies` and `localStorage` without use of `cy.request` or `cy.visit` before every test. 
+* switch between multiple `Sessions` during a single test
+* inspect `Session` data that applied to test in the Command Log
+* quickly iterate as an authenticated user in `Interactive mode` without replaying login steps 
+* keep the convenience and test coverage of UI based authentication while gaining the speed of programmatic login
+* gain massive reductions in spec run time. Since `Session` data is saved after the first time it's used,future tests that share a call to `useSession()` will use near-instant `Session` restoration without needing to perform slow UI actions.
+
+
+# Usage
+
+```ts
+cy.useSession(sessionReference)
+```
+
+
+**Note:** when using `Sessions`, all cookies and localStorage will be cleared before every test *for all domains*.
+
+## Arguments
+
+### **{% fa fa-angle-right %} sessionReference** **_(`string | object`)_**
+
+Specifies the `Session` reference, as previously defined in {% url `cy.defineSession()` defineSession %}, to apply. This is either the name (`string`) of a `Session` or the return value of the {% url `cy.defineSession()` defineSession %} command.
+
+```ts
+cy.useSession('mySession')
+
+// OR
+
+const mySession = cy.defineSession({
+  name: 'mySession'
+  steps () {...}
+})
+
+cy.useSession(mySession)
+```
+
+# Examples
+
+### `Session` applied in a `beforeEach` hook:
+```ts
+// can be placed inside spec or in a cypress/support file
+cy.defineSession({
+  name: 'myUser',
+  steps () {
+    cy.visit('/login')
+    cy.get('.username').type('user')
+    cy.get('.password').type('pass')
+    cy.get('.login').click()
+  }
+})
+
+describe('suite', ()=>{
+  beforeEach(()=>{
+    cy.useSession('myUser')
+    // useSession() always navigates you to a blank page
+    cy.visit('...')
+  })
+
+  it('test one', ()=>{
+    // beforeEach executed session steps
+    // and saved the 'myUser' Session 
+  })
+
+  it('test two', ()=>{
+    // beforeEach did NOT execute session steps
+    // and instantaneously restored saved 'myUser' session data
+  })
+})
+```
+
+### Switch users within a single test
+```ts
+it('admin can ban user', ()=> {
+  cy.useSession('admin')
+  cy.visit('/user/one')
+  cy.get('.ban-user-button').click()
+  // wait for the network request to be completed
+  cy.get('.toast').contains('successfully banned user')
+
+  cy.useSession('basicUser')
+  cy.visit('/home')
+  cy.contains('sorry, you can no longer access this site')
+})
+
+```

source/guides/references/experiments.md

@@ -14,12 +14,14 @@ You can pass the {% url "configuration" configuration %} options below to enable
 
 Option | Default | Description
 ----- | ---- | ----
+`experimentalSessionSupport` | `false` | Enables support for the Cypress Session API. See {% url `useSession`  useSession %} for more detail.
 `experimentalComponentTesting` | `false` | Enables component testing using framework-specific adaptors. See {% url "Component Testing" component-testing-introduction %} for more detail.
 `experimentalFetchPolyfill` | `false` | Automatically replaces `window.fetch` with a polyfill that Cypress can spy on and stub. Note: `experimentalFetchPolyfill` has been deprecated in Cypress 6.0.0 and will be removed in a future release. Consider using {% url "`cy.intercept()`" intercept %} to intercept `fetch` requests instead.
 `experimentalRunEvents` | `false` | Allows listening to the {% url "`before:run`" before-run-api %}, {% url "`after:run`" after-run-api %}, {% url "`before:spec`" before-spec-api %}, and {% url "`after:spec`" after-spec-api %} events in the plugins file.
 `experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See {% issue 5273 %} for details.
 
 {% history %}
+{% url "6.3.0" changelog#6-3-0 %} | Added `experimentSessionSupport`.
 {% url "6.0.0" changelog#6-0-0 %} | Removed `experimentalNetworkStubbing` and made it the default behavior when using {% url "`cy.intercept()`" intercept %}.
 {% url "6.0.0" changelog#6-0-0 %} | Deprecated `experimentalFetchPolyfill`.
 {% url "5.2.0" changelog#5-2-0 %} | Removed `experimentalShadowDomSupport` and made it the default behavior.

themes/cypress/languages/en.yml

@@ -178,6 +178,8 @@ sidebar:
     removelistener: removeListener
     removealllisteners: removeAllListeners
     utilities: Utilities
+    useSession: useSession
+    defineSession: defineSession
     _: _
     $: $
     minimatch: minimatch