add session support to release

source/_data/sidebar.yml

@@ -145,6 +145,8 @@ api:
     type: type.html
     uncheck: uncheck.html
     url: url.html
+    useSession: useSession.html
+    defineSession: defineSession.html
     viewport: viewport.html
     visit: visit.html
     wait: wait.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/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: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.2.0" changelog#6-2-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

@@ -161,6 +161,8 @@ sidebar:
     type: type
     uncheck: uncheck
     url: url
+    useSession: useSession
+    defineSession: defineSession
     viewport: viewport
     visit: visit
     wait: wait