msw-skill AGENTS.md

MSW v2 — Complete Guide

This document is for AI agents and LLMs to follow when writing, reviewing, or debugging MSW (Mock Service Worker) handlers, server setup, and test patterns. It compiles all rules and references into a single executable guide.

Baseline: msw ^2.15.0

---

Abstract

MSW (Mock Service Worker) is a network-level API mocking library for JavaScript/TypeScript. It intercepts HTTP and GraphQL requests using the http and graphql namespaces, returning mock responses via HttpResponse; it also mocks Server-Sent Events with sse and WebSocket connections with ws. In tests, setupServer (from msw/node) intercepts at the request-client level; in the browser, setupWorker (from msw/browser) uses a Service Worker; React Native uses msw/native. MSW v2 completely removed the v1 rest namespace, res(ctx.*) response composition, and (req, res, ctx) resolver signature. This guide covers all v2 patterns, testing best practices, and migration from v1.

---

Table of Contents

1. Handler Design — CRITICAL
2. Setup & Lifecycle — CRITICAL
3. Request Reading — HIGH
4. Response Construction — HIGH
5. Test Patterns — HIGH
6. GraphQL — MEDIUM
7. Utilities — MEDIUM

---

1. Handler Design

Impact: CRITICAL

Rule: Use http Namespace Instead of rest

The rest namespace was removed in MSW 2.0. All HTTP handlers use http.

// INCORRECT — rest does not exist in v2
import { rest } from 'msw'
rest.get('/api/user', (req, res, ctx) => res(ctx.json({ name: 'John' })))

// CORRECT
import { http, HttpResponse } from 'msw'
http.get('/api/user', () => HttpResponse.json({ name: 'John' }))

Rule: Never Put Query Parameters in Handler URL Predicates

MSW matches by pathname only. Query parameters are stripped from the predicate, so including them widens the handler to every request on that path rather than narrowing it. MSW logs a warning when it finds them.