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

setup-

handler-

test-

response-

match-

graphql-

advanced-

debug-

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