Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-skillclaw-36k/skillsmp/msw/AGENTS.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill msw. Copyright stays with the author.

MSW (Mock Service Worker)

Version 1.0.0
mswjs
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive API mocking guide for MSW v2 applications, designed for AI agents and LLMs. Contains 45+ rules across 8 categories, prioritized by impact from critical (setup, handler architecture) to incremental (debugging). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Setup & Initialization — CRITICAL
   • 1.1 Commit Worker Script to Version Control — CRITICAL (Eliminates setup friction for team members; prevents CI failures)
   • 1.2 Configure Server Lifecycle in Test Setup — CRITICAL (Prevents handler leakage and ensures test isolation; eliminates flaky tests)
   • 1.3 Configure TypeScript for MSW v2 — CRITICAL (TypeScript 4.7+ required; incorrect config causes type errors)
   • 1.4 Configure Unhandled Request Behavior — CRITICAL (Catches missing handlers immediately; prevents silent test failures)
   • 1.5 Require Node.js 18+ for MSW v2 — CRITICAL (MSW v2 requires Node 18+; older versions cause complete failure)
   • 1.6 Use Correct Entrypoint for Node.js — CRITICAL (Zero mocking if wrong entrypoint; 100% test failures)
2. Handler Architecture — CRITICAL
   • 2.1 Define Happy Path Handlers as Baseline — CRITICAL (Establishes reliable baseline; enables clean runtime overrides)
   • 2.2 Destructure Resolver Arguments Correctly — CRITICAL (Wrong destructuring pattern causes undefined values; silent failures)
   • 2.3 Explicitly Parse Request Bodies — CRITICAL (v2 no longer auto-parses bodies; missing parsing returns undefined)
   • 2.4 Extract Shared Response Logic into Resolvers — CRITICAL (Eliminates duplication; ensures consistent mock responses across tests)
   • 2.5 Group Handlers by Domain — CRITICAL (Reduces maintenance overhead; scales to large APIs without N×M complexity)
   • 2.6 Share Handlers Across Environments — CRITICAL (Single source of truth; eliminates mock drift between dev/test)
   • 2.7 Use Absolute URLs in Handlers — CRITICAL (Prevents URL mismatch failures; required for Node.js environments)
   • 2.8 Use MSW v2 Response Syntax — CRITICAL (v1 syntax breaks in v2; causes complete handler failure)
3. Test Integration — HIGH
   • 3.1 Avoid Direct Request Assertions — HIGH (Tests implementation details; breaks on refactors that preserve behavior)
   • 3.2 Clear Request Library Caches Between Tests — HIGH (Prevents stale cached responses; ensures fresh mock data per test)
   • 3.3 Configure Fake Timers to Preserve queueMicrotask — HIGH (Prevents request body parsing from hanging indefinitely)
   • 3.4 Reset Handlers After Each Test — HIGH (Prevents handler pollution; eliminates test order dependencies)
   • 3.5 Use Async Testing Utilities for Mock Responses — HIGH (Prevents race conditions; ensures responses arrive before assertions)
   • 3.6 Use Correct JSDOM Environment for Jest — HIGH (Prevents Node.js global conflicts; ensures proper fetch availability)
   • 3.7 Use server.boundary() for Concurrent Tests — HIGH (Enables parallel test execution; prevents cross-test handler pollution)
4. Response Patterns — HIGH
   • 4.1 Add Realistic Response Delays — HIGH (Reveals race conditions; tests loading states; catches timing bugs)
   • 4.2 Mock Streaming Responses with ReadableStream — HIGH (Tests streaming UIs, chat interfaces, and progressive loading)
   • 4.3 Set Response Headers Correctly — HIGH (Ensures CORS, caching, and authentication headers work as expected)
   • 4.4 Simulate Error Responses Correctly — HIGH (Validates error handling; catches missing error states in UI)
   • 4.5 Use HttpResponse Static Methods — HIGH (Automatic Content-Type headers; cleaner syntax; type safety)
   • 4.6 Use One-Time Handlers for Sequential Scenarios — HIGH (Models realistic multi-step flows; tests retry logic correctly)
5. Request Matching — MEDIUM-HIGH
   • 5.1 Access Query Parameters from Request URL — MEDIUM-HIGH (Enables filtering, pagination, and search mocking)
   • 5.2 Match HTTP Methods Explicitly — MEDIUM-HIGH (Prevents cross-method interference; models REST APIs correctly)
   • 5.3 Order Handlers from Specific to General — MEDIUM-HIGH (Prevents general handlers from shadowing specific ones)
   • 5.4 Use Custom Predicates for Complex Matching — MEDIUM-HIGH (Enables header-based, body-based, and conditional request matching)
   • 5.5 Use URL Path Parameters Correctly — MEDIUM-HIGH (Prevents silent handler mismatches; enables dynamic URL matching)
6. GraphQL Mocking — MEDIUM
   • 6.1 Access GraphQL Variables Correctly — MEDIUM (Enables dynamic mock responses based on query input)
   • 6.2 Handle Batched GraphQL Queries — MEDIUM (Supports Apollo batching; prevents unhandled batch requests)
   • 6.3 Return GraphQL Errors in Correct Format — MEDIUM (Ensures GraphQL clients parse errors correctly; tests error handling)
   • 6.4 Use Operation Name for GraphQL Matching — MEDIUM (Enables precise operation targeting; prevents query/mutation conflicts)
7. Advanced Patterns — MEDIUM
   • 7.1 Configure MSW for Vitest Browser Mode — MEDIUM (Enables browser-environment testing with proper worker setup)
   • 7.2 Handle Cookies and Authentication — MEDIUM (Enables session-based auth testing; validates auth flows)
   • 7.3 Implement Dynamic Mock Scenarios — MEDIUM (Enables runtime mock state changes; supports complex test flows)
   • 7.4 Mock File Upload Endpoints — MEDIUM (Tests file upload forms and progress indicators)
   • 7.5 Use bypass() for Passthrough Requests — MEDIUM (Enables mixing real and mocked APIs; supports hybrid testing)
8. Debugging & Performance — LOW
   • 8.1 Know Common MSW Issues and Fixes — LOW (Quick reference for frequent problems; reduces debugging time)
   • 8.2 Log Request Details for Debugging — LOW (Provides detailed request inspection; identifies payload issues)
   • 8.3 Use Lifecycle Events for Debugging — LOW (Provides visibility into request interception; aids troubleshooting)
   • 8.4 Verify Request Interception is Working — LOW (Confirms MSW is active; identifies setup failures early)

References

1. https://mswjs.io/docs/
2. https://mswjs.io/docs/best-practices/
3. https://mswjs.io/docs/migrations/1.x-to-2.x/
4. https://mswjs.io/docs/runbook/
5. https://github.com/mswjs/msw

Source Files

This document was compiled from individual reference files. For detailed editing or extension: