msw

---
name: msw
description: >-
  Assists with intercepting network requests for API mocking using Mock Service Worker (MSW).
  Use when mocking REST or GraphQL APIs for unit tests, integration tests, or local
  development without modifying application code or running mock servers. Trigger words:
  msw, mock service worker, api mocking, test mocking, request handlers, setupServer.
license: Apache-2.0
compatibility: "Requires Node.js 18+"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: development
  tags: ["msw", "testing", "api-mocking", "rest", "graphql"]
---

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