msw-skill_skill

Overview

This skill documents MSW (Mock Service Worker) v2 best practices, patterns, and API guidance for JavaScript and TypeScript tests and local development. It focuses on correct v2 usage, migration from v1, handler design, server/worker setup, response construction, testing patterns, and GraphQL handling. Follow these rules to avoid common pitfalls and keep API mocks reliable and easy to maintain.

How this skill works

The guidance inspects code that imports MSW, uses setupServer/setupWorker, or references http.*, graphql.*, HttpResponse, and related APIs. It enforces v2 resolver and response patterns, lifecycle hooks, and recommended utilities like delay(), passthrough(), and bypass(). It also flags v1 idioms (rest, ctx) and suggests v2 equivalents and migration steps.

When to use it

• Intercept HTTP/GraphQL at the network level for tests or Storybook
• Mock backend behavior during local development without changing app code
• Isolate API edge cases and error responses in unit/integration tests
• Replace fragile module-level mocks when you need realistic network behavior
• Prototype frontend features before backend endpoints are available

Best practices

• Use the http namespace (http.get/post/put/etc.) — rest is removed in v2
• Write resolvers with ({ request, params, cookies }) and await request.json() for bodies
• Return HttpResponse.* (e.g., HttpResponse.json()) instead of res(ctx.*)
• Organize mocks under src/mocks/ with separate node/browser entrypoints and a clear lifecycle: beforeAll, afterEach, afterAll
• Use server.use() for per-test overrides and server.boundary() to isolate concurrent tests
• Set onUnhandledRequest: 'error' during tests to catch unmocked network calls

Example use cases

• Unit/integration tests that assert UI and state while mocking network responses
• Storybook stories that simulate API data and edge cases in the browser worker
• Local development where frontend work continues without a real backend
• Migrating a codebase from MSW v1 to v2 by replacing rest/ctx patterns with http and HttpResponse
• Testing GraphQL clients by scoping endpoints with graphql.link(url) and returning { data } or { errors } via HttpResponse.json()