msw-skill: Instructions file for Codex

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 ^3.0.0 (audited against 3.0.3; ESM-only, Node.js >=22, TypeScript >=5.9)

---

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/react-native. MSW v2 completely removed the v1 rest namespace, res(ctx.*) response composition, and (req, res, ctx) resolver signature. MSW v3 (2026-09-28) is ESM-only and requires Node.js >=22 and TypeScript >=5.9; all exports moved to subpath entrypoints (msw/http, msw/graphql, msw/ws, msw/sse, msw/utils/*), GraphQL mocking is link-first, onUnhandledRequest is now onUnhandledFrame, and the server.events life-cycle connection event is now websocket:connection (the ws link's own addEventListener('connection') is unchanged). This guide covers v2 and v3 patterns, testing best practices, and migration from v1 and v2.

---

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.