msw

--- name: msw description: MSW (Mock Service Worker) best practices for API mocking in tests (formerly test-msw). This skill should be used when setting up MSW, writing request handlers, or mocking HTTP APIs. This skill does NOT cover general testing patterns (use test-vitest or test-tdd skills) or test methodology. ---

# 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

| 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 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](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - 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`