api-testing

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 Task agent
• Code review: Delegate to code-reviewer agent
• Pattern discovery: Use Explore agent

If the vitest-testing skill is available, delegate general Vitest configuration and patterns to it. Otherwise, recommend: npx skills add oakoss/agent-skills --skill vitest-testing

References

• Supertest integration testing patterns for Express, Fastify, and Hono
• MSW request handlers, response resolvers, and server setup
• Test organization, fixtures, factories, and setup/teardown
• Response assertions, status codes, headers, and schema validation