MSW Best Practices
Comprehensive API mocking guide for MSW 3 applications (current: MSW 3.0.4), designed for AI agents and LLMs. Contains 51 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
Version
Targets MSW 3.x (Node.js 22+). Check the msw version in package.json or run npx -y @pymodel/react-frontend-skills detect.
Relative handler paths: in the browser and in jsdom/happy-dom, a relative path resolves against location.href. In a pure Node environment there is no location, so use an absolute URL or */path (see handler-absolute-urls).
When to Apply
Reference these guidelines when:
- Setting up MSW for testing or development
- Writing or organizing request handlers
- Configuring test environments with MSW
- Mocking REST or GraphQL APIs
- Debugging handler matching issues
- Testing error states and edge cases
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Setup & Initialization | CRITICAL | setup- |
| 2 | Handler Architecture | CRITICAL | handler- |
| 3 | Test Integration | HIGH | test- |
| 4 | Response Patterns | HIGH | response- |
| 5 | Request Matching | MEDIUM-HIGH | match- |
| 6 | GraphQL Mocking | MEDIUM | graphql- |
| 7 | Advanced Patterns | MEDIUM | advanced- |
| 8 | Debugging & Performance | LOW | debug- |
Quick Reference
1. Setup & Initialization (CRITICAL)
setup-server-node-entrypoint- Use the correct entrypoint for Node.js (msw/node)setup-v3-handler-entrypoints- Import graphql from msw/graphql; http, HttpResponse, ws, sse and utilities come from mswsetup-lifecycle-hooks- Configure server lifecycle in test setupsetup-worker-script-commit- Commit worker script to version controlsetup-vite-plugin- Serve the worker and enable mocking with the msw/vite pluginsetup-node-version- Require Node.js 22+setup-unhandled-requests- Configure unhandled request behavior with onUnhandledFramesetup-typescript-config- Configure TypeScript for MSW
2. Handler Architecture (CRITICAL)
handler-happy-path-first- Define happy path handlers as baselinehandler-domain-grouping- Group handlers by domainhandler-absolute-urls- Use absolute URLs in Node handlershandler-shared-resolvers- Extract shared response logic into resolvershandler-v2-response-syntax- Return an HttpResponse from every resolverhandler-request-body-parsing- Explicitly parse request bodieshandler-resolver-argument- Destructure resolver arguments correctlyhandler-reusability-environments- Share handlers across environments
3. Test Integration (HIGH)
test-reset-handlers- Reset handlers after each testtest-avoid-request-assertions- Avoid direct request assertionstest-concurrent-boundary- Use server.boundary() for concurrent teststest-fake-timers-config- Configure fake timers to preserve queueMicrotasktest-async-utilities- Use async testing utilities for mock responsestest-clear-request-cache- Clear request library caches between teststest-jsdom-environment- Use correct JSDOM environment for Jest
4. Response Patterns (HIGH)
response-http-response-helpers- Use HttpResponse static methodsresponse-delay-realistic- Add delays only for timing behavior under testresponse-error-simulation- Simulate error responses correctlyresponse-one-time-handlers- Use one-time handlers for sequential scenariosresponse-custom-headers- Set response headers correctlyresponse-streaming- Mock streaming responses with ReadableStream
5. Request Matching (MEDIUM-HIGH)
match-url-patterns- Use URL path parameters correctlymatch-query-params- Access query parameters from request URLmatch-custom-predicate- Use custom predicates for complex matchingmatch-http-methods- Match HTTP methods explicitlymatch-handler-order- Order handlers from specific to general
6. GraphQL Mocking (MEDIUM)
graphql-operation-handlers- Define operations on a graphql.link() by operation namegraphql-error-responses- Return GraphQL errors in correct formatgraphql-batched-queries- Handle batched GraphQL queriesgraphql-variables-access- Access GraphQL variables correctlygraphql-schema-first- Resolve operations against a GraphQL schemagraphql-subscriptions- Mock GraphQL subscriptions with link.subscription()
7. Advanced Patterns (MEDIUM)
advanced-bypass-requests- Use bypass() for passthrough requestsadvanced-cookies-auth- Handle cookies and authenticationadvanced-dynamic-scenarios- Implement dynamic mock scenariosadvanced-vitest-browser- Configure MSW for Vitest browser modeadvanced-file-uploads- Mock file upload endpointsadvanced-websocket-mocking- Mock WebSocket connections with ws.linkadvanced-playwright-integration- Use defineNetworkFixture from @msw/playwright
8. Debugging & Performance (LOW)
debug-lifecycle-events- Use lifecycle events for debuggingdebug-verify-interception- Verify request interception is workingdebug-common-issues- Know common MSW issues and fixesdebug-request-logging- Log request details for debugging
How to Use
Run in the project root first:
npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versionsRead references/<rule-id>.md for each rule above that matches the task: why it matters, then incorrect vs. correct code.
Related Skills
- For consuming mocked APIs, see
tanstack-queryskill - For test framework patterns, see
vitest; for methodology, seetdd