Registry / testing / storage-mock

storage-mock

JSON →
library2.1.0jsnpmunverified

A cross-browser mock of the Web Storage API (localStorage and sessionStorage) that includes full support for the storage event, enabling testing of event listeners in environments like Node.js or headless browsers. The current version is 2.1.0, released with stable maintenance. It differentiates from simpler mocks by providing a complete window-like mock object that dispatches storage events on changes, making it suitable for testing event-driven code. The package is lightweight, has no dependencies, and supports Node.js >=4. It is primarily used in unit testing and CI/CD pipelines to simulate browser storage behavior.

testing
npm install storage-mock
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · STORAGE-MOCK
S
storage-mock
testingjavascriptv2.1.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mockedWindow
✓ const mockedWindow = require('storage-mock');
✗ import mockedWindow from 'storage-mock';
This package does not ship ES module support; use CommonJS require. The default export is a mocked window object.
localStorage
✓ const { localStorage } = require('storage-mock');
✗ const localStorage = require('storage-mock').localStorage;
Both work, but destructuring is cleaner. The localStorage property exists directly on the exported object.
sessionStorage
✓ const { sessionStorage } = require('storage-mock');
sessionStorage is also available as a property of the mocked window object.

Demonstrates creating a mocked window, adding a storage event listener, setting/getting/removing/clearing items, and removing the listener.

const mockedWindow = require('storage-mock'); // Listen for storage events const listener = (e) => { console.log(`Key: ${e.key}, Old: ${e.oldValue}, New: ${e.newValue}`); }; mockedWindow.addEventListener('storage', listener); // Set an item (triggers event) mockedWindow.localStorage.setItem('test-key', 'test-value'); // Get item console.log(mockedWindow.localStorage.getItem('test-key')); // Remove item (triggers event) mockedWindow.localStorage.removeItem('test-key'); // Clear all (triggers event) mockedWindow.localStorage.clear(); // Cleanup mockedWindow.removeEventListener('storage', listener);
Debug
Known issues
gotchaThe mock does not persist data between test suites; each require returns a fresh mock. Use beforeEach to reinitialize if needed.
fix
const mock = require('storage-mock'); beforeEach(() => { mock.localStorage.clear(); mock.sessionStorage.clear(); });
affects: >=0.0.0
deprecatedThe `length` property of localStorage/sessionStorage is writable but may be deprecated in future updates.
fix
Use Object.keys(mock.localStorage).length instead of setting length.
affects: >=1.0.0
gotchaStorage events are not dispatched for same-document changes in real browsers, but the mock dispatches events on all changes. Code relying on this spec behavior may break.
fix
When testing, ensure event listeners do not assume same-origin/tab restrictions.
affects: >=0.0.0
breakingIn version 2.0.0, the exported object changed from a pure storage mock to a full window mock with event listeners attached. Existing code directly using the previous structure will fail.
fix
Wrap usage with the new window-like object: const mock = require('storage-mock'); mock.localStorage.setItem(...);
affects: >=2.0.0 <2.0.0
Errors
Common errors & fixes
TypeError: mockedWindow.addEventListener is not a function
Using an older version (<2.0.0) that did not include event system.
fix
Upgrade to version >=2.0.0: npm install storage-mock@latest
ReferenceError: window is not defined
Attempting to use window.localStorage in Node.js without mock.
fix
Use the mock: const mockedWindow = require('storage-mock'); const localStorage = mockedWindow.localStorage;
Cannot find module 'storage-mock'
Package not installed or typo in package name.
fix
Run: npm install storage-mock --save-dev
Error: Cannot find module 'events'
Missing Node.js built-in 'events' module in very old Node versions (<4).
fix
Upgrade Node.js to version >=4, or polyfill the events module.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/princed/storage-mock ↗
packagestorage-mock ↗
homepagehttps://github.com/princed/storage-mock#readme ↗
storage-mock — npm install storage-mock · libregistry