cypress-localstorage-commands

What is cypress-localstorage-commands?

The cypress-localstorage-commands package provides custom commands for Cypress to interact with the browser's localStorage. It allows you to set, get, and clear localStorage items, which can be useful for testing purposes.

What are cypress-localstorage-commands's main functionalities?

Set LocalStorage Item

This command sets a localStorage item with the specified key and value. It is useful for pre-populating localStorage with data before running tests.

cy.setLocalStorage('key', 'value');

Get LocalStorage Item

This command retrieves the value of a localStorage item by its key. It can be used to verify that the correct data is stored in localStorage during tests.

cy.getLocalStorage('key').then(value => { console.log(value); });

Clear LocalStorage

This command clears all items from localStorage. It is useful for ensuring a clean state before running tests.

cy.clearLocalStorage();

Remove LocalStorage Item

This command removes a specific item from localStorage by its key. It can be used to test the behavior of your application when certain localStorage items are missing.

cy.removeLocalStorage('key');

Other packages similar to cypress-localstorage-commands

cypress-plugin-snapshots

This package provides snapshot testing capabilities for Cypress. While it focuses on visual and DOM snapshots rather than localStorage, it offers a way to ensure that your application's UI remains consistent over time.

README

Cypress localStorage commands

Extends Cypress' cy commands with localStorage methods. Allows preserving localStorage between tests.

The problem

You want to preserve localStorage between Cypress tests.

This solution

This solution allows you to use all browser localStorage methods through Cypress commands, and preserve it between tests.

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm i --save-dev cypress-localstorage-commands

Usage

cypress-localstorage-commands extends Cypress' cy command.

Add this line to your project's cypress/support/commands.js:

import "cypress-localstorage-commands"

You can now use all next commands:

Commands

Save current localStorage values into an internal "snapshot":

cy.saveLocalStorage();

Restore localStorage to previously "snapshot" saved values:

cy.restoreLocalStorage();

Clear localStorage "snapshot" values:

cy.clearLocalStorageSnapshot();

Get localStorage item. Equivalent to localStorage.getItem in browser:

cy.getLocalStorage("item");

Set localStorage item. Equivalent to localStorage.setItem in browser:

cy.setLocalStorage("item", "value");

Remove localStorage item. Equivalent to localStorage.removeItem in browser:

cy.removeLocalStorage("item");

Preserving local storage between tests

Use saveLocalStorage to save a snapshot of current localStorage at the end of one test, and use the restoreLocalStorage command to restore it at the beginning of another one. The usage of beforeEach and afterEach is recommended for this purpose.

Examples

Cookies button example

Next example shows how this package can be used to test a "cookies button" (which theorically sets a flag into localStorage and can be clicked only once)

describe("Accept cookies button", () => {
  const COOKIES_BUTTON = "#accept-cookies";

  before(() => {
    cy.clearLocalStorageSnapshot();
  });

  beforeEach(() => {
    cy.restoreLocalStorage();
    cy.visit("/");
  });

  afterEach(() => {
    cy.saveLocalStorage();
  });

  it("should be visible", () => {
    cy.get(COOKIES_BUTTON).should("be.visible");
  });

  it("should not be visible after clicked", () => {
    cy.get(COOKIES_BUTTON).click();
    cy.get(COOKIES_BUTTON).should("not.be.visible");
  });

  it("should not be visible after reloading", () => {
    cy.get(COOKIES_BUTTON).should("not.be.visible");
  });
});

Note the usage of beforeEach and afterEach for preserving localStorage between all tests. Also clearLocalStorageSnapshot is used in the before statement to avoid possible conflicts with other test files preserving localStorage.

localStorage assertions

Based on the previous example, assertions could be added to check values of localStorage:

describe("localStorage cookies-accepted item", () => {
  beforeEach(() => {
    cy.restoreLocalStorage();
    cy.visit("/");
  });

  afterEach(() => {
    cy.saveLocalStorage();
  });

  it("should be null first time page is visited", () => {
    cy.getLocalStorage("cookies-accepted").should("equal", null);
  });

  it("should be true after clicking cookies button", () => {
    cy.get("#accept-cookies").click();
    cy.getLocalStorage("cookies-accepted").should("equal", "true");
  });

  it("should be true after reloading", () => {
    cy.getLocalStorage("cookies-accepted").then(cookiesAccepted => {
      expect(cookiesAccepted).to.equal("true");
    });
  });
});

Usage with TypeScript

For those writing TypesScript tests in Cypress, this package includes TypeScript declarations.

Add "cypress-localstorage-commands" to the types property of the tsconfig.json file:

{
  "compilerOptions": {
    "types": ["cypress", "cypress-localstorage-commands"]
  }
}

Or reference the package in the files using it:

/// <reference types="cypress-localstorage-commands" />

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.

License

MIT, see LICENSE for details.

Changelog

[1.2.5] - 2020-12-05

Changed

• chore(ci): Migrate CI to github actions. Rename npm commands
• chore(deps): Add Cypress 6.x to peerDependencies
• chore(test): Update Cypress to v6.0.1 in e2e tests
• chore(deps): Update devDependencies