MSW (Mock Service Worker)

Overview

MSW intercepts network requests at the service worker level (browser) or in-memory (Node.js) to mock REST and GraphQL APIs for tests and local development. It uses the same handlers for both environments, keeping mocks consistent, and works transparently with any HTTP client (fetch, axios, Apollo) without modifying application code.

Instructions

• When setting up handlers, define REST handlers with

  http.get()

  ,

  http.post()

  , etc. and GraphQL handlers with

  graphql.query()

  and

  graphql.mutation()

  , returning responses via

  HttpResponse.json()

  .
• When testing in Node.js, use

  setupServer(...handlers)

  with

  server.listen()

  before tests,

  server.resetHandlers()

  between tests, and

  server.close()

  after all tests.
• When developing in the browser, use

  setupWorker(...handlers)

  and run

  npx msw init ./public

  to generate the service worker file, which intercepts requests visible in DevTools.
• When overriding per test, use

  server.use()

  to add temporary handlers for error states or edge cases, which scope to the current test and reset afterward.
• When simulating network issues, use

  delay(ms)

  for latency,

  HttpResponse.error()

  for failures, and custom status codes for error responses.
• When organizing handlers, keep shared handlers in

  src/mocks/handlers.ts

  for reuse across test files and the dev server, with per-test overrides via

  server.use()

  .

Examples

Example 1: Mock a REST API for component tests

User request: "Set up MSW to mock my user API for React Testing Library tests"

Actions:

1. Define handlers in

   src/mocks/handlers.ts

   for GET

   /api/users

   , POST

   /api/users

   , and GET

   /api/users/:id

2. Set up

   setupServer(...handlers)

   in the test setup file with beforeAll/afterEach/afterAll hooks
3. Write component tests that render with data from the mock API
4. Add per-test error overrides with

   server.use(http.get("/api/users", () => HttpResponse.json(null, { status: 500 })))

Output: Component tests with realistic API mocking, including happy path and error state coverage.

Example 2: Mock a GraphQL API for development

User request: "Set up MSW to mock my GraphQL API during local development"

Actions:

1. Define GraphQL handlers for queries (

   GetPosts

   ,

   GetUser

   ) and mutations (

   CreatePost

   )
2. Set up

   setupWorker(...handlers)

   in the browser entry point with conditional activation
3. Add

   delay(300)

   to simulate realistic network latency
4. Run

   npx msw init ./public

   and start the dev server

Output: A development environment with mocked GraphQL API visible in browser DevTools, with realistic latency.

Guidelines

• Use MSW in both tests and development with the same handlers to keep mocks consistent.
• Define handlers in a shared

  src/mocks/handlers.ts

  file for reuse across test files and the dev server.
• Use

  server.use()

  for per-test overrides; keep the default happy path in shared handlers.
• Always mock error states in tests to verify error handling works correctly.
• Use

  delay()

  in development mocks to simulate real latency and catch loading state bugs.
• Reset handlers after each test with

  afterEach(() => server.resetHandlers())

  to prevent test pollution.