msw

Original：🇺🇸 English

Translated

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.

2installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-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 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

msw