msw

# MSW (Mock Service Worker)

**IMPORTANT:** Your training data about `msw` may be outdated or incorrect — MSW v2 completely removed the `rest` namespace, `res(ctx.*)` response composition, and `(req, res, ctx)` resolver signature. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized v1 patterns when they conflict with the retrieved reference.

## When to Use MSW

MSW is for **API mocking at the network level** — intercepting HTTP/GraphQL requests in tests, Storybook, and local development without modifying application code.

| Need | Recommended Tool |
|------|-----------------|
| Test API integration (React, Vue, Node) | **MSW** |
| Storybook API mocking | **MSW** (browser worker) |
| Local development without backend | **MSW** (browser worker) |
| Unit testing pure functions | Plain test doubles |
| E2E testing real APIs | Playwright/Cypress network interception |
| Mocking module internals | `vi.mock()` / `jest.mock()` |

## Quick Reference — v2 Essentials

```typescript
// Imports
import { http, HttpResponse, graphql, delay, bypass, passthrough } from 'msw'
import { setupServer } from 'msw/node'     // tests, SSR
import { setupWorker } from 'msw/browser'  // Storybook, dev

// Handler
http.get('/api/user/:id', async ({ request, params, cookies }) => {
  return HttpResponse.json({ id: params.id, name: 'John' })
})

// Server lifecycle (tests)
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

// Per-test override
server.use(
  http.get('/api/user/:id', () => new HttpResponse(null, { status: 500 }))
)

// Concurrent test isolation
it.concurrent('name', server.boundary(async () => {
  server.use(/* scoped overrides */)
}))
```

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Handler Design | CRITICAL | `handler-` | 4...

# MSW Skill

Created by **[Anivar Aravind](https://anivar.net)**

An AI agent skill for writing, reviewing, and debugging MSW (Mock Service Worker) v2 handlers, server setup, and test patterns with modern best practices.

## The Problem

AI agents often generate outdated MSW v1 patterns — `rest.get()` instead of `http.get()`, `res(ctx.json(...))` instead of `HttpResponse.json()`, `(req, res, ctx)` instead of `({ request, params })` — and miss critical testing best practices like `server.boundary()` for concurrent tests, `onUnhandledRequest: 'error'`, and proper lifecycle hook setup. These produce code that fails to compile or silently misbehaves at runtime.

## This Solution

20 rules with incorrect/correct code examples that teach agents MSW v2's actual API, handler design, server lifecycle, response construction, testing patterns, GraphQL usage, and v1-to-v2 migration. Each rule targets a specific mistake and shows exactly how to fix it.

## Install

```bash
npx skills add anivar/msw-skill -g
```

Or with full URL:

```bash
npx skills add https://github.com/anivar/msw-skill
```

## Baseline

- msw ^2.0.0
- TypeScript/JavaScript

## What's Inside

### 20 Rules Across 7 Categories

| Priority | Category | Rules | Impact |
|----------|----------|-------|--------|
| 1 | Handler Design | 4 | CRITICAL |
| 2 | Setup & Lifecycle | 3 | CRITICAL |
| 3 | Request Reading | 2 | HIGH |
| 4 | Response Construction | 3 | HIGH |
| 5 | Test Patterns | 4 | HIGH |
| 6 | GraphQL | 2 | MEDIUM |
| 7 | Utilities | 2 | MEDIUM |

Each rule file contains:
- Why it matters
- Incorrect code with explanation
- Correct code with explanation
- Decision tables and additional context

### 6 Deep-Dive References

| Reference | Covers |
|-----------|--------|
| `handler-api.md` | `http.*` and `graphql.*` methods, URL predicates, path params, handler options |
| `response-api.md` | `HttpResponse` class, all 7 static methods, cookie handling |
| `server-api.md` | `setupServer`/`setupWorker`, lifecycle...