msw

Original：🇺🇸 English

Translated

Current MSW v2 guidance for request handlers, Node/browser setup, HTTP and GraphQL mocking, test isolation, timing, and debugging. General test framework patterns are covered by vitest and methodology by tdd.

2installs

Sourcepymodel/react-frontend-skills

Added on2026-08-24

NPX Install

npx skill4agent add pymodel/react-frontend-skills msw

SKILL.md Content

View Translation Comparison →

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-

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 delays only for timing behavior under test
```
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
Individual rules:
```
references/{prefix}-{slug}.md
```

Related Skills

For consuming mocked APIs, see
```
tanstack-query
```
skill
For test framework patterns, see
```
vitest
```
; for methodology, see
```
tdd
```

Full Compiled Document

For the complete guide with all rules expanded:

AGENTS.md

msw