Some rearrangement, etc. Updated examples to use more realistic data.

source/api/commands/defineSession.md

@@ -7,9 +7,12 @@ containerClass: experimental
 {% 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.
+Defines a Session. A Session is a collection of `cookies` and `localStorage` across all domains that may be restored at any point during a test with the accompanying {% url `cy.useSession()` useSession %} command.
+
+# Syntax
 
 ## Usage
+
 ```ts
 cy.defineSession(name, steps, options?)
 cy.defineSession(options)
@@ -18,23 +21,29 @@ 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.
+
+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.
+
+A function containing the Cypress commands needed to set `Session` data. For example, the commands required to log in to 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 %}
+`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.
+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` file 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 %}
+
+# See also
+
+* {% url `cy.useSession()` useSession %}

source/api/commands/useSession.md

@@ -7,32 +7,34 @@ containerClass: experimental
 {% 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` created when using the accompanying {% url `cy.defineSession()` defineSession %} command.
 
-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...
 
-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.
+* 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 during `cypress open` without replaying login steps.
+* keep the convenience and test coverage of UI based authentication while gaining the speed of programmatic login.
+* reduce your spec run time. Since Session data is saved after the first time it's used, future tests that share a call to `cy.useSession()` will use Session restoration without needing to perform slower UI actions.
 
+{% note warning %}
+**Note:** when using Sessions, all cookies and localStorage will be cleared before every test *for all domains*.
+{% endnote %}
+
+# Syntax
 
-# Usage
+## 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.
+Specifies the Session reference to apply, as previously defined in {% url `cy.defineSession()` defineSession %}. This is either the name (`string`) of a Session or the return value of the {% url `cy.defineSession()` defineSession %} command.
 
 ```ts
 cy.useSession('mySession')
@@ -49,50 +51,57 @@ cy.useSession(mySession)
 
 # Examples
 
-### `Session` applied in a `beforeEach` hook:
+## Session applied in a `beforeEach` hook
+
 ```ts
 // can be placed inside spec or in a cypress/support file
 cy.defineSession({
-  name: 'myUser',
+  name: 'userLoggedIn',
   steps () {
     cy.visit('/login')
-    cy.get('.username').type('user')
-    cy.get('.password').type('pass')
+    cy.get('.username').type('janelane')
+    cy.get('.password').type('secret1')
     cy.get('.login').click()
   }
 })
 
-describe('suite', ()=>{
+describe('as a logged in user', ()=>{
   beforeEach(()=>{
-    cy.useSession('myUser')
+    cy.useSession('userLoggedIn')
     // useSession() always navigates you to a blank page
-    cy.visit('...')
+    cy.visit('/profile')
   })
 
-  it('test one', ()=>{
+  it('correct user shown in profile', ()=>{
     // beforeEach executed session steps
-    // and saved the 'myUser' Session 
+    // and saved the 'userLoggedIn' Session 
+    cy.get('.profile-name').should('contain', 'Jane')
   })
 
-  it('test two', ()=>{
+  it('user can log out', ()=>{
     // beforeEach did NOT execute session steps
-    // and instantaneously restored saved 'myUser' session data
+    // and instead restored saved 'userLoggedIn' session data
+    cy.get('.logout-btn').click()
   })
 })
 ```
 
-### Switch users within a single test
+## 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()
+  cy.visit('/users/nefarious')
+  cy.get('.ban-user-btn').click()
   // wait for the network request to be completed
   cy.get('.toast').contains('successfully banned user')
 
-  cy.useSession('basicUser')
-  cy.visit('/home')
+  cy.useSession('nefariousUser')
+  cy.visit('/dashboard')
   cy.contains('sorry, you can no longer access this site')
 })
-
 ```
+
+# See also
+
+* {% url `cy.defineSession()` defineSession %}