MSW Best Practices

Comprehensive API mocking guide for MSW v2 applications, designed for AI agents and LLMs. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

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

Quick Reference

1. Setup & Initialization (CRITICAL)

• •setup-server-node-entrypoint - Use correct entrypoint for Node.js (msw/node)
• •setup-lifecycle-hooks - Configure server lifecycle in test setup
• •setup-worker-script-commit - Commit worker script to version control
• •setup-node-version - Require Node.js 18+ for MSW v2
• •setup-unhandled-requests - Configure unhandled request behavior
• •setup-typescript-config - Configure TypeScript for MSW v2

2. Handler Architecture (CRITICAL)

• •handler-happy-path-first - Define happy path handlers as baseline
• •handler-domain-grouping - Group handlers by domain
• •handler-absolute-urls - Use absolute URLs in handlers
• •handler-shared-resolvers - Extract shared response logic into resolvers
• •handler-v2-response-syntax - Use MSW v2 response syntax
• •handler-request-body-parsing - Explicitly parse request bodies
• •handler-resolver-argument - Destructure resolver arguments correctly
• •handler-reusability-environments - Share handlers across environments

3. Test Integration (HIGH)

• •test-reset-handlers - Reset handlers after each test
• •test-avoid-request-assertions - Avoid direct request assertions
• •test-concurrent-boundary - Use server.boundary() for concurrent tests
• •test-fake-timers-config - Configure fake timers to preserve queueMicrotask
• •test-async-utilities - Use async testing utilities for mock responses
• •test-clear-request-cache - Clear request library caches between tests
• •test-jsdom-environment - Use correct JSDOM environment for Jest

4. Response Patterns (HIGH)

• •response-http-response-helpers - Use HttpResponse static methods
• •response-delay-realistic - Add realistic response delays
• •response-error-simulation - Simulate error responses correctly
• •response-one-time-handlers - Use one-time handlers for sequential scenarios
• •response-custom-headers - Set response headers correctly
• •response-streaming - Mock streaming responses with ReadableStream

5. Request Matching (MEDIUM-HIGH)

• •match-url-patterns - Use URL path parameters correctly
• •match-query-params - Access query parameters from request URL
• •match-custom-predicate - Use custom predicates for complex matching
• •match-http-methods - Match HTTP methods explicitly
• •match-handler-order - Order handlers from specific to general

6. GraphQL Mocking (MEDIUM)

• •graphql-operation-handlers - Use operation name for GraphQL matching
• •graphql-error-responses - Return GraphQL errors in correct format
• •graphql-batched-queries - Handle batched GraphQL queries
• •graphql-variables-access - Access GraphQL variables correctly

7. Advanced Patterns (MEDIUM)

• •advanced-bypass-requests - Use bypass() for passthrough requests
• •advanced-cookies-auth - Handle cookies and authentication
• •advanced-dynamic-scenarios - Implement dynamic mock scenarios
• •advanced-vitest-browser - Configure MSW for Vitest browser mode
• •advanced-file-uploads - Mock file upload endpoints

8. Debugging & Performance (LOW)

• •debug-lifecycle-events - Use lifecycle events for debugging
• •debug-verify-interception - Verify request interception is working
• •debug-common-issues - Know common MSW issues and fixes
• •debug-request-logging - Log request details for debugging

How to Use

Read individual reference files for detailed explanations and code examples:

• •Section definitions - Category structure and impact levels
• •Rule template - Template for adding new rules
• •Individual rules: references/{prefix}-{slug}.md

Related Skills

• •For generating MSW mocks from OpenAPI, see orval skill
• •For consuming mocked APIs, see tanstack-query skill
• •For test methodology, see test-vitest or test-tdd skills

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md