From 3e33341154c9e039df347513cd578262ea31480b Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 15:44:38 -0600 Subject: [PATCH 1/9] docs around Cypress.session api --- content/api/cypress-api/session.md | 98 ++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 5 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index cdce435fa3..92d97dd7d3 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -2,22 +2,110 @@ title: Cypress.session --- -`Cypress.session` is a collection of session-related helper methods intended to -be used alongside the [`cy.session()`](/api/commands/session) command. +`Cypress.session` is a collection of async session-related helper methods +intended to be used alongside the [`cy.session()`](/api/commands/session) +command. ## Syntax -Clear all saved sessions and re-run the current spec file. - ```javascript +// Clear all sessions, include cached global sessions, saved on the backend. Cypress.session.clearAllSavedSessions() +// Clear all storage and cookie date across all origins associated with the current session. +Cypress.session.clearCurrentSessionData() +// Get all storage and cookie date across all origins associated with the current session. +Cypress.session.getCurrentSessionData() +// Get all storage and cookie date saved on the backend associated with the provided session id. +Cypress.session.getSession(id) ``` -This can also be done by clicking the "Clear All Sessions" button in the +Clearing all session and automatically re-running the spec +`Cypress.session.clearAllSavedSessions()` can also be done by clicking the +"Clear All Sessions" button in the [Sessions Instrument Panel](/api/commands/session#The-Instrument-Panel). +### Arguments + +** id** **_(String)_** + +The name of the session whom's data storage and cookie date you'd like to +retrieve. + +## Examples + +### Clearing the all session data + +By default, Cypress will clear the current session data **before** each test +when `testIsolation` is enabled. However, to you can remove all cached session +data with `Cypress.session.clearAllSavedSessions()`. + +```js +Cypress.session.clearAllSavedSessions() +``` + +### Clearing the current session data when testIsolation is disabled + +By default, Cypress will clear the current session data **before** each test +when `testIsolation` is enabled. If you have disabled `testIsolation` for a +suite, it can be helpful to clear the current session data in a `before()` block +to ensure the suite started in a clean test slate. + +```js +describe('Dashboard', { testIsolation: false }, () => { + before(() => { + // ensure clean test slate for these tests + cy.then(Cypress.session.clearCurrentSessionData) + }) +}) +``` + +### Verified the Applied Session Data + +To check all cookies, localStorage and sessionStorage that was applied after +`cy.session()` completes. You can use `Cypress.session.getCurrentSessionData()`. +This can be helpful for quickly analyzing the current browser context while +writing you `cy.session()` command. + +Since this is an all-in-one helper of the `cy.getAllCookies()`, +`cy.getAllLocalStorage()` and `cy.getAllSessionStorage()` commands, we generally +recommend leverage the commands for asserting the correct session data has been +applied in the session validation. + +```js +it('debug session', () => { + cy.session('id', () => { + ... + }) + cy.then(async () => { + const sessionData = await Cypress.session.getCurrentSessionData() + cy.debug()s + }) +}) +``` + +### Debugging Cached Session Data + +If your session seems to be recreated more than expected, or doesn't seem to be +applying the cookies, `localStorage` or `sessionStorage` data that you'd expect, +you can use `Cypress.session.getSession(id)` to view what session data has been +cached by `cy.session()`. If you are missing any data, your setup and/or +validate function may not be waiting long enough for all attributes to be +applied to there page before the `cy.session()` command saves and finishes. + +```js +it('debug session', () => { + cy.session('id', () => { + ... + }) + cy.then(async () => { + const sessionData = await Cypress.session.getSession('id') + cy.debug() + }) +}) +``` + ## See also - [`cy.session()`](/api/commands/session) From 62cbd6c8d12c777ccc2a6c336f774c16743c45af Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 15:47:38 -0600 Subject: [PATCH 2/9] data not date --- content/api/cypress-api/session.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 92d97dd7d3..743d6e4069 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -13,9 +13,9 @@ command. Cypress.session.clearAllSavedSessions() // Clear all storage and cookie date across all origins associated with the current session. Cypress.session.clearCurrentSessionData() -// Get all storage and cookie date across all origins associated with the current session. +// Get all storage and cookie data across all origins associated with the current session. Cypress.session.getCurrentSessionData() -// Get all storage and cookie date saved on the backend associated with the provided session id. +// Get all storage and cookie data saved on the backend associated with the provided session id. Cypress.session.getSession(id) ``` @@ -30,7 +30,7 @@ Clearing all session and automatically re-running the spec ** id** **_(String)_** -The name of the session whom's data storage and cookie date you'd like to +The name of the session whom's data storage and cookie data you'd like to retrieve. ## Examples From c929c851a591f77abbd15f672e3778591c1bb30a Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 16:02:38 -0600 Subject: [PATCH 3/9] Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes --- content/api/cypress-api/session.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 743d6e4069..238a4511bd 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -38,7 +38,7 @@ retrieve. ### Clearing the all session data By default, Cypress will clear the current session data **before** each test -when `testIsolation` is enabled. However, to you can remove all cached session +when `testIsolation` is enabled. You can also remove all cached session data with `Cypress.session.clearAllSavedSessions()`. ```js From 57772b34606d1f32e0c01e2feb0af45d9612c755 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 16:02:49 -0600 Subject: [PATCH 4/9] Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes --- content/api/cypress-api/session.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 238a4511bd..4dc71c28d8 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -30,8 +30,7 @@ Clearing all session and automatically re-running the spec ** id** **_(String)_** -The name of the session whom's data storage and cookie data you'd like to -retrieve. +The name of the session used to retrieve data storage and cookie data. ## Examples From 2fce0961b69272af18e73a1666994809d56c52ac Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 16:03:04 -0600 Subject: [PATCH 5/9] Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes --- content/api/cypress-api/session.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 4dc71c28d8..070ea406d0 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -63,9 +63,9 @@ describe('Dashboard', { testIsolation: false }, () => { ### Verified the Applied Session Data To check all cookies, localStorage and sessionStorage that was applied after -`cy.session()` completes. You can use `Cypress.session.getCurrentSessionData()`. +`cy.session()` completes, you can use `Cypress.session.getCurrentSessionData()`. This can be helpful for quickly analyzing the current browser context while -writing you `cy.session()` command. +writing your `cy.session()` command. Since this is an all-in-one helper of the `cy.getAllCookies()`, `cy.getAllLocalStorage()` and `cy.getAllSessionStorage()` commands, we generally From d37f4d6c1c61c6bee73832a0ad7ee8f6e2036b97 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 16:03:28 -0600 Subject: [PATCH 6/9] Update content/api/cypress-api/session.md Co-authored-by: Matt Henkes --- content/api/cypress-api/session.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 070ea406d0..4852e4ad3d 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -69,8 +69,8 @@ writing your `cy.session()` command. Since this is an all-in-one helper of the `cy.getAllCookies()`, `cy.getAllLocalStorage()` and `cy.getAllSessionStorage()` commands, we generally -recommend leverage the commands for asserting the correct session data has been -applied in the session validation. +recommend leveraging these commands for asserting the correct session data has been +applied in the session validation block. ```js it('debug session', () => { From 3823d0908b129727877585220bed96fe06977352 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Mon, 5 Dec 2022 16:56:53 -0600 Subject: [PATCH 7/9] fix markdown --- content/api/cypress-api/session.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 4852e4ad3d..b92baf62af 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -37,8 +37,8 @@ The name of the session used to retrieve data storage and cookie data. ### Clearing the all session data By default, Cypress will clear the current session data **before** each test -when `testIsolation` is enabled. You can also remove all cached session -data with `Cypress.session.clearAllSavedSessions()`. +when `testIsolation` is enabled. You can also remove all cached session data +with `Cypress.session.clearAllSavedSessions()`. ```js Cypress.session.clearAllSavedSessions() @@ -69,8 +69,8 @@ writing your `cy.session()` command. Since this is an all-in-one helper of the `cy.getAllCookies()`, `cy.getAllLocalStorage()` and `cy.getAllSessionStorage()` commands, we generally -recommend leveraging these commands for asserting the correct session data has been -applied in the session validation block. +recommend leveraging these commands for asserting the correct session data has +been applied in the session validation block. ```js it('debug session', () => { From abf2e3a5bfc833c9366611e2013ea8f004317779 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Tue, 6 Dec 2022 07:53:27 -0600 Subject: [PATCH 8/9] Update content/api/cypress-api/session.md --- content/api/cypress-api/session.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index b92baf62af..796fd24187 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -9,7 +9,7 @@ command. ## Syntax ```javascript -// Clear all sessions, include cached global sessions, saved on the backend. +// Clear all sessions saved on the backend, including cached global sessions. Cypress.session.clearAllSavedSessions() // Clear all storage and cookie date across all origins associated with the current session. Cypress.session.clearCurrentSessionData() From 448ece1be95c6606342183548c8a18bee8f52647 Mon Sep 17 00:00:00 2001 From: Emily Rohrbough Date: Tue, 6 Dec 2022 07:53:58 -0600 Subject: [PATCH 9/9] Apply suggestions from code review --- content/api/cypress-api/session.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/api/cypress-api/session.md b/content/api/cypress-api/session.md index 796fd24187..13df5bbfff 100644 --- a/content/api/cypress-api/session.md +++ b/content/api/cypress-api/session.md @@ -77,7 +77,7 @@ it('debug session', () => { cy.session('id', () => { ... }) - cy.then(async () => { + .then(async () => { const sessionData = await Cypress.session.getCurrentSessionData() cy.debug()s }) @@ -98,7 +98,7 @@ it('debug session', () => { cy.session('id', () => { ... }) - cy.then(async () => { + .then(async () => { const sessionData = await Cypress.session.getSession('id') cy.debug() })