Testing APIs

Tests are what let you change an API with confidence. Three layers, each catching a different class of bug, give good coverage without redundant effort.

The layers

flowchart TD
  U[Unit: handlers, validation, pure logic - many, fast] --> I[Integration: real routes end-to-end - fewer]
  I --> C[Contract: responses match the OpenAPI spec - focused]

Many fast unit tests, fewer integration tests, focused contract checks

• Unit tests — exercise pure pieces: a validator, a pagination helper, an error mapper. Fast and numerous.
• Integration tests — send real requests through the actual router and assert status, headers, and body. These catch wiring bugs unit tests miss.
• Contract tests — assert that responses conform to the OpenAPI schema, so the implementation and the published contract never drift.

An integration-style assertion

Frameworks like Hono expose app.request(...), so you can call routes in-process without a network:

JavaScriptRun ▸Open in StackBlitz ▸

// Simulating an assertion an integration test would make. function assert(name, cond) { console.log((cond ? 'PASS' : 'FAIL') + ': ' + name); } // Pretend this is the response from app.request('/articles/0') const response = { status: 404, body: { title: 'Not found', status: 404 } }; assert('missing article returns 404', response.status === 404); assert('error body echoes status', response.body.status === 404); assert('error body has a title', typeof response.body.title === 'string');

What to assert

For each endpoint, test the happy path and the failure paths: the right status code, the response shape, the error body for invalid input (does it match your problem+json?), auth required where expected, and pagination metadata on collections.

Common mistakes

Testing only the happy path Symptom:

• Tests only send valid requests — resource created, status 201
• Never test validation errors, auth failures, not-found, or conflicts
• Test every error path for every status code the API documents

Mocking the database in integration tests Symptom:

• Integration tests mock the database — the real query never runs
• Bad SQL or a broken constraint passes in tests but fails in production
• Use a real test database (in-memory SQLite or a test container)

💡 Real-world examples

Stripe:

• Test-mode API keys run tests against the real Stripe environment without moving real money
• Webhook testing via the Stripe CLI: stripe listen --forward-to localhost:3000/webhook

GitHub:

• No separate sandbox API — teams test against disposable test repos/orgs instead
• Contract tests against the published OpenAPI spec catch drift in CI before it ships

Sources: Stripe testing, Stripe CLI webhooks, GitHub REST API description

🌐 Test the failures, not just the happy path

Most production incidents live in the error and edge paths — the 404, the 422, the expired token, the empty page. Assert those explicitly. Contract tests against your OpenAPI spec are especially high-value: they fail the moment your implementation drifts from what you have promised consumers.

Which test layer sends real requests through the actual router?

Unit tests Integration tests Contract tests Load tests

What do contract tests specifically guard against?

Slow responses The implementation drifting from the published OpenAPI contract Database downtime Large payloads

Why explicitly test failure paths?

They are easier to write Many incidents live in error/edge paths (404, 422, expired token, empty page) HTTP requires it To increase the test count only

Submit

Mark as complete