Skip to main content

Cypress.session

Cypress.session is a collection of async session-related helper methods intended to be used alongside the cy.session() command.

Syntax​

// 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()
// Get all storage and cookie data across all origins associated with the current session.
Cypress.session.getCurrentSessionData()
// Get all storage and cookie data saved on the backend associated with the provided session id.
Cypress.session.getSession(id)

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.

Sessions Instrument Panel

Arguments​

id (String)

The name of the session used to retrieve data storage and cookie data.

Examples​

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().

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.

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 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.

it('debug session', () => {
    cy.session('id', () => {
        ...
    })
    .then(async () => {
        const sessionData = await Cypress.session.getCurrentSessionData()
        cy.debug()
    })
})

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.

it('debug session', () => {
    cy.session('id', () => {
        ...
    })
    .then(async () => {
        const sessionData = await Cypress.session.getSession('id')
        cy.debug()
    })
})

See also​

Contents