| name | api-mocking |
| description | API mock configuration for tests. Trigger when the user wants to mock APIs, use MSW, or test without a backend. |
| allowed-tools | ["Read","Write","Edit","Glob","Grep","Bash"] |
| context | fork |
| user-invocable | false |
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:
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 workqa-e2e — Playwright/Cypress tests often layer MSW for deterministic stubsdev-tdd (test-infrastructure setup) — wires the global setupServer into vitest/jest config
