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.


Jest 24+

Note that with jest@24 and above this project potentially duplicating functionality.

Install

This should only be installed as a development dependency (devDependencies) as
it is only designed for testing. The module is transpiled via
babel to support the current active Node LTS
version (6.11.3).

yarn:

``bash
yarn add --dev jest-localstorage-mock
`

npm:

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

Setup

The simplest setup is to use the module system, you may also choose
to create a setup file if needed.

$3

In your package.json under the jest
configuration section
create a setupFiles array and add jest-localstorage-mock to the array. Also, ensure you have not enabled resetMocks.

`json
{
"jest": {
"resetMocks": false,
"setupFiles": ["jest-localstorage-mock"]
}
}
`

If you already have a setupFiles attribute you can also append
jest-localstorage-mock to the array.

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

$3

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

`js
import 'jest-localstorage-mock';
// or
require('jest-localstorage-mock');
`

Add that file to your setupFiles array:

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

$3

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

`js
require('jest-localstorage-mock');
`

You must also override some of create-react-app's default jest configuration. You can do so in your package.json:

`json
{
"jest": {
"resetMocks": false
}
}
`

For more information, see #125.

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.

$3

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

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

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

`js
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);
});
`

Reset your localStorage data and mocks before each test to prevent leaking.

`js
beforeEach(() => {
// to fully reset the state between tests, clear the storage
localStorage.clear();
// and reset all mocks
jest.clearAllMocks();

// clearAllMocks will impact your other mocks too, so you can optionally reset individual mocks instead:
localStorage.setItem.mockClear();
});

test('should not impact the next test', () => {
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);
});

test('should not be impacted by the previous test', () => {
const KEY = 'baz',
VALUE = 'zab';
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);
});
``

See the contributing guide for details on how you can
contribute.