Mocking APIs
Overview
Generate mock API servers from OpenAPI specifications that return realistic, schema-compliant response data for development and testing. Support dynamic response generation with Faker.js data, configurable latency simulation, stateful CRUD behavior, and request recording for contract testing validation.
Prerequisites
- OpenAPI 3.0+ specification file with response schema definitions
- Mock server runtime: Prism (Stoplight), json-server, MSW (Mock Service Worker), or WireMock
- Faker.js or equivalent for realistic test data generation
- Docker for containerized mock server deployment (optional but recommended)
- Frontend or consumer application needing API stubs for parallel development
Instructions
- Read the OpenAPI specification using Read and extract all endpoint definitions, response schemas, and example values to build the mock response inventory.
- Generate response fixtures for each endpoint using schema-aware data generation: realistic names (Faker), valid emails, properly formatted dates, and relational IDs that reference other mock entities.
- Configure the mock server to match requests by method, path pattern, query parameters, and request body content type, returning the appropriate fixture.
- Add stateful behavior for CRUD operations: POST creates a record in memory, GET returns it, PUT updates it, DELETE removes it -- enabling realistic integration testing flows.
- Implement configurable response delays (50-500ms per endpoint) to simulate real-world latency and test client timeout handling.
- Add error scenario mocking: configure specific request patterns to return 400, 401, 404, 429, or 500 responses for testing error handling paths.
- Enable request recording that captures all incoming requests with timestamps and headers for later replay in contract tests.
- Create a startup script that launches the mock server on a configurable port with hot-reload when fixture files change.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/mocks/server.js - Mock server entry point with route registration${CLAUDE_SKILL_DIR}/mocks/fixtures/ - Per-endpoint response fixture JSON files${CLAUDE_SKILL_DIR}/mocks/generators/ - Dynamic response generators using Faker.js${CLAUDE_SKILL_DIR}/mocks/scenarios/ - Error scenario configurations (4xx, 5xx responses)${CLAUDE_SKILL_DIR}/mocks/state.js - In-memory state store for CRUD behavior${CLAUDE_SKILL_DIR}/mocks/recordings/ - Captured request logs for contract testing${CLAUDE_SKILL_DIR}/docker-compose.mock.yml - Docker configuration for mock server
Error Handling
| Error | Cause | Solution |
|---|
| Schema mismatch | Mock response does not match updated OpenAPI spec | Run spec-to-fixture sync on spec change; add CI check comparing fixture schemas |
| Missing endpoint | Consumer requests path not defined in OpenAPI spec | Return 501 with message listing available endpoints; log unknown path for spec update |
| Stale fixtures | Mock data becomes unrealistic after API schema evolution | Regenerate fixtures from latest spec; use generators over static fixtures for evolving APIs |
| Port conflict | Mock server port already in use by another dev service | Make port configurable via environment variable; default to spec-defined server URL port |
| State leak between tests | Stateful mock retains data from previous test run | Reset in-memory state before each test suite; expose POST /mock/reset admin endpoint |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
Frontend parallel development: Launch a Prism mock server from the OpenAPI spec so frontend developers can build against realistic API responses while backend implementation is in progress.
Integration test isolation: Use MSW (Mock Service Worker) to intercept HTTP requests in Node.js test suites, returning fixture responses without network calls, with per-test response customization.
Contract testing: Record all requests to the mock server during frontend E2E tests, then replay them against the real backend to verify the mock accurately represents actual API behavior.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
