jest-localstorage-mock

What is jest-localstorage-mock?

The jest-localstorage-mock package is a Jest mock for the localStorage API, allowing developers to test code that interacts with localStorage without relying on the actual browser implementation. This can help ensure tests are isolated and run consistently across different environments.

What are jest-localstorage-mock's main functionalities?

Mocking localStorage

This feature allows you to mock the localStorage API, enabling you to test interactions with localStorage without relying on the actual browser implementation. The code sample demonstrates how to set an item in localStorage and verify that it was set correctly.

const localStorageMock = require('jest-localstorage-mock');

// Example test
it('should store an item in localStorage', () => {
  localStorage.setItem('key', 'value');
  expect(localStorage.setItem).toHaveBeenCalledWith('key', 'value');
  expect(localStorage.getItem('key')).toBe('value');
});

Clearing localStorage

This feature allows you to clear the localStorage, which is useful for ensuring a clean state between tests. The code sample demonstrates setting an item in localStorage and then clearing it, verifying that the item is no longer present.

const localStorageMock = require('jest-localstorage-mock');

// Example test
it('should clear localStorage', () => {
  localStorage.setItem('key', 'value');
  localStorage.clear();
  expect(localStorage.getItem('key')).toBeNull();
});

Removing an item from localStorage

This feature allows you to remove a specific item from localStorage. The code sample demonstrates setting an item in localStorage, removing it, and verifying that it has been removed.

const localStorageMock = require('jest-localstorage-mock');

// Example test
it('should remove an item from localStorage', () => {
  localStorage.setItem('key', 'value');
  localStorage.removeItem('key');
  expect(localStorage.getItem('key')).toBeNull();
});

Other packages similar to jest-localstorage-mock

localstorage-memory

localstorage-memory is an in-memory implementation of the localStorage API. It can be used in Node.js environments to simulate localStorage without relying on a browser. Compared to jest-localstorage-mock, localstorage-memory is more focused on providing a full in-memory localStorage implementation rather than just mocking it for tests.

node-localstorage

node-localstorage is a package that provides a localStorage implementation for Node.js. It writes data to disk, making it persistent across sessions. This is different from jest-localstorage-mock, which is designed specifically for mocking localStorage in tests and does not provide persistence.

mock-local-storage

mock-local-storage is another package that mocks the localStorage and sessionStorage APIs for testing purposes. It is similar to jest-localstorage-mock but also includes support for sessionStorage, providing a more comprehensive solution for testing storage APIs.

README

Use this module with Jest to run web tests that rely on localstorage and / or sessionStorage where you want a working localStorage API with mocked functions.

This module has no runtime dependencies so your project won't pull in additional module dependencies by using this.

Install

This should only be required as a dev dependency when your tests are running.

yarn:

yarn add --dev jest-localstorage-mock

npm:

npm i --save-dev jest-localstorage-mock

Setup

Module

In your package.json under the jest section add the module name to the setupFiles array. This is by far the simplest method for using this.

"jest": {
  "setupFiles": [
    "jest-localstorage-mock"
  ]
}

You can also append this to the array if you have other setup files.

"jest": {
  "setupFiles": [
    "./__setups__/other.js",
    "jest-localstorage-mock"
  ]
}

Setup file

Alternatively you can create a new setup file which then requires this module or add the require statement to an existing setup file.

__setups__/localstorage.js

require('jest-localstorage-mock');

Add that file to your setupFiles array:

"jest": {
  "setupFiles": [
    "./__setups__/localstorage.js"
  ]
}

In create-react-app

For a create-react-app project you can replace the suggested mock with this at the beginning of the existing src/setupTests.js file:

require("jest-localstorage-mock");

In tests

By including this in your Jest setup you'll allow tests that expect a localStorage and sessionStorage object to continue to run. The module can also allow you to use the mocks provided to check that your localStorage is being used as expected.

The __STORE__ attribute of localStorage.__STORE__ or sessionStorage.__STORE__ is made available for you to directly access the storage object if needed.

Test Examples

Check that your localStorage calls were made when they were supposed to.

test('should save to localStorage', () => {
  const KEY = 'foo', VALUE = 'bar';
  dispatch(action.update(KEY, VALUE));
  expect(localStorage.setItem).toHaveBeenLastCalledWith(KEY, VALUE);
  expect(localStorage.__STORE__[KEY]).toBe(VALUE);
  expect(Object.keys(localStorage.__STORE__).length).toBe(1);
});

Check that your sessionStorage is empty, examples work with either localStorage or sessionStorage.

test('should have cleared the sessionStorage', () => {
  dispatch(action.reset());
  expect(sessionStorage.clear).toHaveBeenCalledTimes(1);
  expect(sessionStorage.__STORE__).toEqual({}); // check store values
  expect(sessionStorage.length).toBe(0); // or check length
});

Check that localStorage calls were not made when they shouldn't have been.

test('should not have saved to localStorage', () => {
  const KEY = 'foo', VALUE = 'bar';
  dispatch(action.notIdempotent(KEY, VALUE));
  expect(localStorage.setItem).not.toHaveBeenLastCalledWith(KEY, VALUE);
  expect(Object.keys(localStorage.__STORE__).length).toBe(0);
});

Development

yarn install
yarn test

Pull Request

Before every PR run the following:

yarn run prettier

Publish

When publishing a new build, run the following:

yarn run prettier
yarn run build
npm version `${version}`
npm publish
git push --tags