How does cy.session work and when should you use it?

cy.session takes an identifier and a setup function. The first call runs the setup and saves the resulting browser state. Later calls with the same identifier restore the saved state instead of re-running the setup. It is the supported way to reuse authentication while keeping test isolation.

beforeEach(() => {
  cy.session(["asha", "admin"], () => {
    cy.request({
      method: "POST",
      url: "/api/auth/login",
      body: { email: "asha@example.com", password: "secret123" },
    }).then((response) => {
      cy.setCookie("session", response.body.token);
    });

    cy.visit("/dashboard");
    cy.location("pathname").should("eq", "/dashboard");
  });
});

Options and behaviour

• The identifier can be a string or a serialisable array such as a user and role
• validate runs before restoring a cached session and can force a fresh setup
• cacheAcrossSpecs reuses the session across spec files in the same run
• The setup function should include an assertion that the session works
• A session does not seed backend data; it only restores browser state

cy.session("admin", () => {
  cy.loginByApi("admin@example.com", "secret123");
}, {
  cacheAcrossSpecs: true,
  validate() {
    cy.request("/api/auth/me").its("status").should("eq", 200);
  },
});