msw-handlers

Overview

Mock Service Worker (MSW) intercepts HTTP requests at the network layer using Service Workers in the browser and a request- interception adapter in Node.js (msw-getting-started (opens in new window)). The same handler set works for both - the test author writes one http.get mock and uses it from Vitest unit tests AND from a Cypress browser test.

When to use

• The project is JavaScript / TypeScript.
• Tests need to mock HTTP at the same layer as the SUT - intercepting actual fetch / XHR calls rather than stubbing the HTTP client library.
• Both browser tests (Cypress / Playwright) and Node tests (Vitest / Jest) need the same mock data - MSW's cross-environment consistency is its key advantage.
• The team wants per-test handler overrides (server.use(...)) layered on top of project-wide defaults.

If the project is JVM, use wiremock-stubs. For multi-protocol mocking (TCP / SMTP / LDAP / gRPC), see the Mountebank reference in wiremock-stubs.

Install

npm i msw --save-dev

(Per msw-getting-started (opens in new window).)

For browser setup, also generate the worker script:

npx msw init public/ --save

This places mockServiceWorker.js in your public directory; the worker script is what the browser registers to intercept requests.

Authoring handlers

Per msw-getting-started (opens in new window):

// src/mocks/handlers.js
import { http, HttpResponse } from 'msw';

export const handlers = [
  http.get('https://api.example.com/user', () => {
    return HttpResponse.json({ id: 'abc-123', firstName: 'John' });
  }),

  http.post('https://api.example.com/orders', async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ order_id: 42, ...body }, { status: 201 });
  }),

  http.get('https://api.example.com/orders/:id', ({ params }) => {
    return HttpResponse.json({ order_id: Number(params.id), status: 'shipped' });
  }),
];

Handler signature: http.<verb>(url, resolver). The resolver receives { request, params, cookies } and returns an HttpResponse.

HttpResponse static helpers

The init object accepts status, statusText, headers - matching the standard Response API.

Pattern matching

Browser setup - setupWorker

// src/mocks/browser.js
import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);

// Start the worker only in development / test
if (process.env.NODE_ENV !== 'production') {
  worker.start();
}

(Per msw-getting-started (opens in new window).)

In a Storybook + MSW combo, kick off worker.start() from the preview file. For Cypress: register the worker before any test that depends on the mocks.

Node setup - setupServer

// src/mocks/node.js
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

// vitest.setup.js (or jest.setup.js)
import { server } from './src/mocks/node';

beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

(Per msw-getting-started (opens in new window).)

onUnhandledRequest: 'error' is the canonical strict mode - fails the test if the SUT makes any HTTP call that doesn't have a matching handler. Catches "we forgot to mock that endpoint" silently passing.

Per-test handler overrides

import { http, HttpResponse } from 'msw';
import { server } from './src/mocks/node';

test('handles 500 error gracefully', async () => {
  server.use(
    http.get('https://api.example.com/user', () =>
      new HttpResponse(null, { status: 500 })
    )
  );

  const result = await fetchUser();
  expect(result.error).toBe('server error');
});
// `server.resetHandlers()` in afterEach reverts to the default handlers

This pattern is the canonical way to test error / edge paths without polluting the default-handlers set.

CI integration

# .github/workflows/test.yml
- run: npm ci
- run: npm test          # Vitest / Jest pick up vitest.setup / jest.setup automatically

For Cypress + MSW, also run npx msw init in CI to ensure the service worker script is in public/.

Anti-patterns

Limitations

• Service Worker scope. Browser MSW only intercepts requests from the same origin / path scope as the worker registration. Cross-origin requests need explicit handler URLs.
• Streaming responses. SSE / chunked responses work but are more delicate than JSON; consult MSW docs for the streaming API.
• No native scenario state. Stateful workflows ("after POST, GET returns the new item") need to manage state in your handlers manually (e.g. with a closure-scoped variable).

References

• msw-getting-started (opens in new window) - install, handler authoring, browser vs node setup, lifecycle hooks, server.use() per-test overrides.
• MSW Docs - https://mswjs.io/docs/
• wiremock-stubs - JVM counterpart; its references/mountebank.md covers the multi-protocol alternative.