api-testing
API testing patterns with supertest, MSW, and Vitest. Covers integration testing for REST APIs, HTTP request mocking with Mock Service Worker v2, response assertions, schema validation, test organization, and framework-specific patterns for Express, Fastify, and Hono. Use when writing integration tests for REST APIs, mocking HTTP requests, or testing API endpoints. Use for api-test, supertest, msw, mock-service-worker, integration-test, http-mock, endpoint-test, request-test.
- License 许可
- MIT
- 最近更新
- 2026-09-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- api-testing
- license
- MIT
- metadata
- { "author": "oakoss", "source": "https://mswjs.io/docs", "version": "1.0" }
- description
- API testing patterns with supertest, MSW, and Vitest. Covers integration testing for REST APIs, HTTP request mocking with Mock Service Worker v2, response assertions, schema validation, test organization, and framework-specific patterns for Express, Fastify, and Hono. Use when writing integration tests for REST APIs, mocking HTTP requests, or testing API endpoints. Use for api-test, supertest, msw, mock-service-worker, integration-test, http-mock, endpoint-test, request-test.
- user-invocable
- false
02 资源文件 4
- 参考文档references/assertion-patterns.md8.5 KB
- 参考文档references/msw-handlers.md7.3 KB
- 参考文档references/supertest-patterns.md7.6 KB
- 参考文档references/test-organization.md8.3 KB
03 SKILL.md 正文
API Testing
Overview
API testing validates HTTP endpoints by sending requests and asserting responses, covering status codes, headers, body content, and error handling. Supertest provides a fluent chainable API for integration testing against Express, Fastify, and Hono apps without starting a real server. MSW (Mock Service Worker) v2 intercepts outgoing HTTP requests at the network level, enabling realistic mocking of external services in both Node.js tests and browser environments.
When to use: Integration tests for REST APIs, testing middleware pipelines, validating request/response contracts, mocking third-party APIs in tests, testing error handling and edge cases.
When NOT to use: Unit testing pure functions (use direct assertions), E2E browser testing (use Playwright/Cypress), load/performance testing (use k6/Artillery), testing static file serving.
Quick Reference
| Pattern | API | Key Points |
|---|---|---|
| GET request | request(app).get('/path') |
Returns supertest Test object |
| POST with body | request(app).post('/path').send(body) |
Automatically sets Content-Type |
| Auth header | .set('Authorization', 'Bearer token') |
Chain before .expect() |
| Status assertion | .expect(200) |
Chainable with body assertions |
| Body assertion | .expect({ key: 'value' }) |
Deep equality check |
| Header assertion | .expect('Content-Type', /json/) |
Accepts string or regex |
| MSW HTTP handler | http.get('/api/users', resolver) |
Intercepts matching requests |
| MSW GraphQL handler | graphql.query('GetUser', resolver) |
Intercepts by operation name |
| MSW response | HttpResponse.json(data, { status }) |
v2 response format |
| MSW error simulation | HttpResponse.error() |
Simulates network failure |
| MSW one-time handler | http.get(path, resolver, { once: true }) |
Auto-removed after first match |
| MSW per-test override | server.use(handler) |
Override default handlers in specific tests |
| Schema validation | schema.parse(response.body) |
Validates response structure with Zod |
| Cookie persistence | const agent = request.agent(app) |
Maintains cookies across requests |
| Fastify inject | app.inject({ method, url }) |
Built-in testing without supertest |
| Hono test client | testClient(app) |
Type-safe request builder |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Not awaiting supertest requests | Always await request(app).get('/path') |
| Sharing server state between tests | Reset handlers with server.resetHandlers() in afterEach |
| Mocking fetch/axios directly | Use MSW to intercept at the network level |
Forgetting server.listen() in setup |
Call in beforeAll, resetHandlers in afterEach |
| Passing Fastify instance to supertest | Use fastify.server (the underlying Node server) |
| Asserting before response completes | Use await or return the supertest chain |
| Hardcoding test data across many tests | Use factories or fixtures for test data |
| Not testing error responses | Test 4xx and 5xx paths alongside happy paths |
Using server.close() in afterEach |
Use afterAll for close, afterEach for reset only |
| Ignoring response headers in assertions | Validate Content-Type, Cache-Control, CORS headers |
Not using onUnhandledRequest: 'error' |
Catch unhandled requests to prevent silent test gaps |
| Testing implementation instead of behavior | Assert on response shape, not internal function calls |
Delegation
- Test structure review: Use
Taskagent - Code review: Delegate to
code-revieweragent - Pattern discovery: Use
Exploreagent
If the
vitest-testingskill is available, delegate general Vitest configuration and patterns to it. Otherwise, recommend:npx skills add oakoss/agent-skills --skill vitest-testing
References
04 同仓库更多 Skills
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
turborepo
Turborepo monorepo build system and orchestration. Covers task pipelines, dependsOn syntax, caching configuration, remote cache, filtering, CI optimization, environment variables, workspace management, watch mode, package boundaries, and code generation. Use when configuring tasks, creating packages, setting up monorepo, sharing code between apps, running changed packages, debugging cache, optimizing CI, resolving workspace dependencies, enforcing package boundaries, or generating code.
tailwind
Tailwind CSS v4 patterns and design systems. Use when configuring Tailwind themes, building components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, or fixing build errors. Use for tailwind, css, styling, theme, design-tokens.
pnpm-workspace
pnpm workspace monorepo management with filtering, catalogs, and shared configs. Use when setting up monorepos, managing workspace dependencies, filtering package commands, or sharing configuration across packages.
material-theme-builder
Generate Material Design 3 color themes programmatically from a source color using @material/material-color-utilities, the same engine that powers the Material Theme Builder. Use this when the user asks to generate an M3 color palette, create a custom theme from a brand color, or export M3 tokens to CSS, JSON, or framework configs.
material-design-3-typography
Applies Material Design 3 Expressive typography principles including variable fonts, type scales, and hierarchy. Use this when working on text styling, type hierarchy, readable interfaces, or when the user asks to apply Material Design 3 typography guidelines.