# API Mocking

> API mock configuration for tests. Trigger when the user wants to mock APIs, use MSW, or test without a backend.

- Skill: `christopherlouet/api-mocking` (Agent Skill)
- Install (CLI): `npx skillmds@latest add christopherlouet/api-mocking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/christopherlouet/api-mocking/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: christopherlouet (https://skillmd.com/u/christopherlouet)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/christopherlouet/api-mocking

---


# API Mocking (pointer)

MSW handler API, browser/node setup, install commands and request-interception internals are canonical at vendor docs and drift on each release:

- **MSW** — [mswjs.io](https://mswjs.io) (recommended default; browser worker + Node server, single handler set)
- **nock** — [github.com/nock/nock](https://github.com/nock/nock) (Node-only HTTP interception)
- **json-server** — [github.com/typicode/json-server](https://github.com/typicode/json-server) (full REST fake server from a JSON file)
- **Mirage JS** — [miragejs.com](https://miragejs.com) (browser-only, models + factories)

## Tool selection (version-agnostic)

```
Need to mock HTTP for tests/dev?
├── Browser AND Node from one handler set → MSW
├── Node-only unit tests, low ceremony → nock
├── Need a stateful REST fake server (CRUD) → json-server
└── Browser-only with relational fixtures (factories) → Mirage JS
```

## Foundation discipline (keep across releases)

- **Type-safe mocks**: derive mock payloads from the same TypeScript types as the real API (e.g. shared `types/api.ts`). A mock that compiles against stale types is the #1 source of mock-prod divergence.
- **Reset between tests**: always `resetHandlers()` (MSW) or `cleanAll()` (nock) in `afterEach` — leaked state across tests is a debugging tax.
- **Realistic failure modes**: simulate 5xx/timeouts/auth errors, not just happy paths. The mock is only useful if it exercises the same edge cases as prod.
- **Unhandled = error**: in tests use `onUnhandledRequest: 'error'` (MSW) so a typo'd URL fails loudly instead of silently passing.

## See also

- `dev-tdd` — mocks live in test setup; this skill activates from TDD work
- `qa-e2e` — Playwright/Cypress tests often layer MSW for deterministic stubs
- `dev-tdd` (test-infrastructure setup) — wires the global `setupServer` into vitest/jest config