# jest-localstorage-mock

> Auto mock all localstorage and sessionstorage APIs for your Jest tests

Latest version **2.4.26** (published 2023-01-04) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install jest-localstorage-mock
pnpm add jest-localstorage-mock
yarn add jest-localstorage-mock
bun add jest-localstorage-mock
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.26 |
| Published | 2023-01-04 |
| First published | 2017-05-06 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=6.16.0 |
| Dependencies | 0 |
| Unpacked size | 20.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 319 |
| Author | Bryan Clark |
| Maintainers | clarkbw |
| Keywords | jest, test, mock, localstorage, sessionstorage, storage, node, browser |

## Links

- npm: https://www.npmjs.com/package/jest-localstorage-mock
- Repository: https://github.com/clarkbw/jest-localstorage-mock
- Issues: https://github.com/clarkbw/jest-localstorage-mock/issues
- npm.io page: https://npm.io/package/jest-localstorage-mock

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 2.4.26 (latest) — 2023-01-04
- 2.4.25 — 2022-12-15
- 2.4.24 — 2022-12-15
- 2.4.23 — 2022-12-15
- 2.4.22 — 2022-08-11
- 2.4.21 — 2022-04-11
- 2.4.20 — 2022-04-11
- 2.4.19 — 2022-02-15
- 2.4.18 — 2021-09-21
- 2.4.17 — 2021-08-23
- 2.4.16 — 2021-08-12
- 2.4.15 — 2021-08-12
- 2.4.14 — 2021-06-01
- 2.4.13 — 2021-05-25
- 2.4.12 — 2021-05-10
- … 21 more at https://npm.io/package/jest-localstorage-mock/versions

## README

Use this module with [Jest](https://facebook.github.io/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.

[![npm](https://img.shields.io/npm/v/jest-localstorage-mock.svg)](https://www.npmjs.com/package/jest-localstorage-mock)
[![npm](https://img.shields.io/npm/l/jest-localstorage-mock.svg)](https://github.com/clarkbw/jest-localstorage-mock/blob/master/LICENSE)
[![Codecov](https://img.shields.io/codecov/c/github/clarkbw/jest-localstorage-mock.svg)](https://codecov.io/gh/clarkbw/jest-localstorage-mock)
[![Greenkeeper badge](https://badges.greenkeeper.io/clarkbw/jest-localstorage-mock.svg)](https://greenkeeper.io/)
[![Twitter](https://img.shields.io/twitter/url/https/github.com/clarkbw/jest-localstorage-mock.svg?style=social)](https://twitter.com/intent/tweet?text=Wow:&url=%5Bobject%20Object%5D)

# 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](https://github.com/babel/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](#module) system, you may also choose
to create a [setup file](#setup-file) if needed.

### Module

In your `package.json` under the `jest`
[configuration section](https://facebook.github.io/jest/docs/en/configuration.html#content)
create a `setupFiles` array and add `jest-localstorage-mock` to the array. Also, ensure you have *not* enabled [`resetMocks`](https://jestjs.io/docs/en/configuration#resetmocks-boolean).

```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"]
  }
}
```

### 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`

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

Add that file to your `setupFiles` array:

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

### In create-react-app

For a [create-react-app](https://github.com/facebookincubator/create-react-app)
project you can replace the
[suggested mock](https://github.com/facebookincubator/create-react-app/tree/master/packages/react-scripts/template#srcsetuptestsjs-1)
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](https://github.com/clarkbw/jest-localstorage-mock/issues/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.

### Test Examples

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](./CONTRIBUTING.md) for details on how you can
contribute.

---
_Source: https://npm.io/package/jest-localstorage-mock · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._