Registry / testing / msw
library2.13.4jsnpmunverified

Mock Service Worker (MSW) is a powerful and seamless library for intercepting and mocking REST and GraphQL API requests directly at the network level, in both browser and Node.js environments. Unlike traditional mocking libraries that patch client-side request utilities, MSW leverages the Service Worker API in browsers and a custom `http` interception module in Node.js. This approach allows applications to run against mock data without any code changes, making it ideal for consistent mocking across development, unit, integration, and end-to-end testing, as well as debugging. The current stable version is 2.13.4, with frequent minor and patch releases, often several times a month, indicating active development. Its key differentiator is providing deviation-free mocking by intercepting actual network requests, ensuring a high fidelity simulation of real API interactions.

npm install msw
INSTALL
IMPORT
SIG · MSW
M
msw
testingjavascriptv2.13.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

setupWorker
import { setupWorker } from 'msw/browser'
const { setupWorker } = require('msw')
Used for browser environments. MSW v2+ is an ESM-only package, so `require` syntax for `setupWorker` will fail. The entry point also changed from `msw` to `msw/browser` in v2.
setupServer
import { setupServer } from 'msw/node'
import { setupServer } from 'msw'
Used for Node.js environments (e.g., testing). MSW v2+ requires importing from `msw/node`. `require` syntax will also fail.
http
import { http } from 'msw'
import { rest } from 'msw'
The `http` object is used for defining REST API request handlers. In MSW v2, the `rest` object from v1 was renamed to `http` for clarity and consistency.
HttpResponse
import { HttpResponse } from 'msw'
Provides utilities for constructing mock HTTP responses, including status, headers, and body. Commonly used within handler resolvers.

This quickstart demonstrates setting up a browser-based Mock Service Worker to intercept and respond to HTTP GET and POST requests, followed by actual `fetch` calls that are intercepted by the mock server.

import { setupWorker, http, HttpResponse } from 'msw'; // Define handlers for your API requests const handlers = [ http.get('https://example.com/api/user/:userId', ({ params }) => { const { userId } = params; if (userId === '123') { return HttpResponse.json( { id: '123', name: 'John Doe', email: 'john.doe@example.com' }, { status: 200 } ); } return HttpResponse.json({ message: 'User not found' }, { status: 404 }); }), http.post('https://example.com/api/users', async ({ request }) => { const newUser = await request.json(); console.log('New user creation request:', newUser); return HttpResponse.json({ id: 'new-id', ...newUser }, { status: 201 }); }) ]; // Create a service worker instance const worker = setupWorker(...handlers); // Register the Service Worker in the browser worker.start({ onUnhandledRequest: 'warn' // Configure behavior for unhandled requests }); console.log('MSW service worker started.'); // Example usage: Make a fetch request that will be intercepted by MSW async function demonstrateMocking() { try { console.log('Fetching user 123...'); const userResponse = await fetch('https://example.com/api/user/123'); const userData = await userResponse.json(); console.log('Fetched user (mocked):', userData); console.log('Creating a new user...'); const createUserResponse = await fetch('https://example.com/api/users', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Jane Smith', email: 'jane.smith@example.com' }) }); const newUserData = await createUserResponse.json(); console.log('Created user (mocked):', newUserData); } catch (error) { console.error('Fetch error:', error); } } demonstrateMocking();
Debug
Known issues
breakingMSW v2 is an ESM-only package and no longer supports CommonJS (`require`). All imports must use ESM syntax (`import`).
fix
Migrate your project to use ECMAScript Modules (ESM) syntax (`import ... from '...'`) and ensure your `package.json` has `"type": "module"` or uses `.mjs` file extensions. Update your bundler/build configuration if necessary.
affects: >=2.0.0
breakingThe `rest` object for defining HTTP handlers was renamed to `http` in MSW v2. Similarly, the `graphql` object also underwent changes in its API.
fix
Replace `rest.get`, `rest.post`, etc., with `http.get`, `http.post`, and similar for other HTTP methods. Review the official migration guide for other API changes in v2, particularly for GraphQL handlers.
affects: >=2.0.0
breakingThe package entry points for browser and Node.js setups changed in MSW v2. Browser setup now imports from `msw/browser` and Node.js from `msw/node`.
fix
Update your import statements: `import { setupWorker } from 'msw'` becomes `import { setupWorker } from 'msw/browser'` for browser usage, and `import { setupServer } from 'msw'` becomes `import { setupServer } from 'msw/node'` for Node.js usage.
affects: >=2.0.0
gotchaEnsuring the Service Worker script (`mockServiceWorker.js`) is correctly served at the root of your application's public directory is crucial for browser environments. Incorrect paths or server configurations can prevent the worker from registering.
fix
Run `npx msw init <PUBLIC_DIR_PATH>` to automatically generate/update the worker script. Verify that the `mockServiceWorker.js` file is accessible at the root of your application (e.g., `http://localhost:3000/mockServiceWorker.js`). If using a custom path, ensure `setupWorker` is configured with `serviceWorker.url`.
affects: >=1.0.0
gotchaWhen using MSW in Node.js test environments (e.g., Jest, Vitest), it's important to properly set up the lifecycle hooks (`beforeAll`, `afterAll`, `afterEach`) to start and stop the server and reset handlers.
fix
Wrap your `setupServer` calls in test framework lifecycle hooks:
`beforeAll(() => server.listen());`
`afterEach(() => server.resetHandlers());`
`afterAll(() => server.close());`
Refer to MSW documentation for specific test runner integrations.
affects: >=1.0.0
Errors
Common errors & fixes
SyntaxError: Named export 'setupWorker' not found. The requested module 'msw' does not provide an export named 'setupWorker'
Attempting to use CommonJS `require` or incorrect ESM import syntax for MSW v2, which is ESM-only, or importing `setupWorker` from the wrong entry point (`msw` instead of `msw/browser`).
fix
Ensure you are using `import { setupWorker } from 'msw/browser'` and that your project is configured for ESM. For Node.js, use `import { setupServer } from 'msw/node'`.
Failed to register a Service Worker: A bad HTTP response code (404) was received when fetching the script.
The `mockServiceWorker.js` file is not found at the expected path (usually the public root) by the browser when `worker.start()` is called.
fix
Verify that `mockServiceWorker.js` is present in your public directory and accessible. Run `npx msw init <PUBLIC_DIR_PATH>` to re-initialize it. Check your web server configuration to ensure it serves static files correctly from the root path. If using a custom path, specify it in `setupWorker({ serviceWorker: { url: '/custom/path/mockServiceWorker.js' } })`.
TypeError: Cannot read properties of undefined (reading 'listen') at server.listen
The `server` object returned by `setupServer` is either undefined or not properly instantiated, often due to incorrect import or setup in a Node.js environment.
fix
Ensure `setupServer` is correctly imported as `import { setupServer } from 'msw/node'` and that the `server` variable is assigned the result of `setupServer(...)`.
Error: [MSW] The 'rest' handler is deprecated and will be removed in the next major version. Please use 'http' instead.
Using the deprecated `rest` object from MSW v1 instead of the `http` object for defining request handlers in an MSW v2 environment.
fix
Replace `rest.get`, `rest.post`, `rest.put`, `rest.patch`, `rest.delete` with their `http` equivalents (e.g., `http.get`, `http.post`).
Upgrade
Version history
2.13.4latest on npm
Audit
Dependencies
typescriptoptionalPeer dependency for TypeScript projects (ships types). While not strictly required for JavaScript-only projects, it's essential for type-safety and optimal developer experience in TypeScript.
Agent activity
4 hits · last 30 days
node
4
Resources