How to Use cy.session in Cypress for Efficient Session Management

Use cy.session in Cypress to cache and restore user sessions during tests, which speeds up test execution by avoiding repeated logins. You provide a unique session identifier and a callback to set up the session once, then Cypress reuses it automatically in later tests.

Syntax

The cy.session command takes two main arguments: a sessionId (a unique string or array identifying the session) and a setup callback function that performs the login or session setup steps. Optionally, you can add an options object for advanced control.

• sessionId: Unique key to identify the session.
• setupCallback: Function to create the session (e.g., login steps).
• options: Optional settings like validation or cache behavior.

javascript

cy.session(sessionId, setupCallback, options?)

Example

This example shows how to use cy.session to cache a login session. The session is created once by logging in, then reused in subsequent tests to avoid logging in repeatedly.

javascript

describe('Using cy.session example', () => {
  beforeEach(() => {
    cy.session('user-session', () => {
      cy.visit('/login')
      cy.get('input[name="username"]').type('testuser')
      cy.get('input[name="password"]').type('password123')
      cy.get('button[type="submit"]').click()
      cy.url().should('include', '/dashboard')
    })
  })

  it('should show dashboard after login', () => {
    cy.visit('/dashboard')
    cy.contains('Welcome, testuser').should('be.visible')
  })

  it('should keep session for another test', () => {
    cy.visit('/profile')
    cy.contains('User Profile').should('be.visible')
  })
})

Output

Test run passes with both tests accessing pages without re-logging in, speeding up execution.

Common Pitfalls

• Not using a unique sessionId causes session conflicts or overwrites.
• Forgetting to include all login steps inside the setupCallback means the session won't be properly cached.
• Trying to use cy.session with commands outside the callback leads to errors.
• Not validating the session state can cause flaky tests if the session expires.

Always keep session setup self-contained and use unique keys.

javascript

/* Wrong way: sessionId not unique and partial login steps outside callback */
cy.session('user-session', () => {
  cy.visit('/login')
})
cy.get('input[name="username"]').type('testuser') // Outside callback - wrong

/* Right way: all login steps inside callback */
cy.session('user-session', () => {
  cy.visit('/login')
  cy.get('input[name="username"]').type('testuser')
  cy.get('input[name="password"]').type('password123')
  cy.get('button[type="submit"]').click()
})

Quick Reference

Parameter	Description	Example
sessionId	Unique key to identify the session	'user-session' or ['user', 'admin']
setupCallback	Function to create the session (login steps)	() => { cy.visit('/login'); ... }
options	Optional settings like validate or cacheAcrossSpecs	{ validate: () => cy.get('#logout') }

Key Takeaways

Use cy.session to cache login or setup steps and speed up tests by reusing sessions.

Always provide a unique sessionId and include all session setup steps inside the callback.

Validate session state if needed to avoid flaky tests due to expired sessions.

Do not run commands outside the setup callback when using cy.session.

Use options to customize session validation and caching behavior.