Integration testing an HTTP API

What an integration test covers that a unit test can’t

Ask yourself: when was the last time a bug in your unit-test-covered code still made it to production? Chances are it lived at a seam — middleware ordering, a wrong status code, auth wired to the wrong path. That is the gap integration tests close.

A unit test pins one function with its collaborators stubbed: fast, focused, and blind to wiring. An integration test exercises the whole request path — router → middleware chain → handler → (usually) the real database — through the actual HTTP surface. That is exactly where a class of bugs lives that unit tests structurally cannot reach: middleware ordering, a forgotten await in a route, a serializer that drops a field, a status code that’s 200 when it should be 201, a content negotiation mismatch, an auth guard wired to the wrong path. The handler can be individually correct and the assembly still broken.

In the test pyramid, integration tests sit above unit tests and below end-to-end: more of them than E2E (which drives a real browser/network and is slow and flaky), fewer than units. The payoff per test is high — one integration test covers many units’ worth of seams — but each costs more to run, so you don’t write thousands. The classic failure is an “ice-cream cone”: almost all tests at the slow end, a hollow middle, and contract bugs leaking to production.

supertest: real HTTP calls without managing a port

supertest wraps any Node http request handler — an Express or Fastify app, or a bare (req, res) => … — and on each call boots it on an ephemeral port (or dispatches in-process), fires a real HTTP request, and tears the listener down. You never pick a port, never risk EADDRINUSE from a hard-coded 3000, and you assert on the real status line, headers, and parsed body.

import { test } from "node:test";
import assert from "node:assert/strict";
import request from "supertest";
import { app } from "../src/app.js"; // do NOT call app.listen() here

test("POST /users creates a user", async () => {
  const res = await request(app)
    .post("/users")
    .send({ email: "a@b.com" })   // sets JSON body + content-type
    .expect("Content-Type", /json/)
    .expect(201);

  assert.equal(res.body.email, "a@b.com");
  assert.match(res.headers.location, /^\/users\/\d+$/);
});

Pass the app itself, not a running server — supertest manages the listener so the test owns the lifecycle. Because the call goes over real HTTP, it catches the wiring bug from the hook: middleware order, body parsing, and the status code are all in play, not stubbed away.

A real database: four strategies, four tradeoffs

The database is where integration tests earn their keep — and where they go wrong. Four common approaches:

Rollback wraps each test in a transaction and aborts it at the end — nothing commits, so the next test sees a clean database with zero reset cost. It’s the fastest with strong isolation, but it can’t test code that itself commits or relies on transaction visibility (you can’t roll back what your code already committed, and nested-transaction tricks change semantics). Truncate/reset is simpler and lets you test commit logic, at the cost of an explicit cleanup write between tests. Testcontainers spins up a real Postgres or Redis in a throwaway Docker container per suite: highest fidelity because it’s the same engine, version, and SQL dialect as production — at the price of seconds of container startup. In-memory SQLite is fast and tempting, but it’s a different database: it won’t enforce your Postgres types, lacks JSONB, RETURNING, partial indexes, and many constraints, so a green SQLite suite can hide SQL that explodes on the real Postgres in prod. Prefer a real engine (Testcontainers) for fidelity; reach for rollback when suite speed dominates.

Isolation, and the open-handle hang

An integration suite is only trustworthy if every test is independent: no leftover rows from a previous test, no ordering dependence, no shared mutable state. Seed deterministic fixtures inside each test (or a fresh per-test transaction), point the suite at a dedicated test database or schema — never a shared dev DB — and give parallel workers separate schemas or databases so two workers don’t fight over the same rows. The hook’s flake is the canonical violation: tests against a shared DB become order-dependent, mutually destructive, and pass-or-fail by luck.

The second classic failure is the process that won’t exit. If you open a server listener or a DB connection pool and never close them, the Node test runner finishes its assertions but the event loop still has live handles, so the process hangs (or warns about open handles / leaked timers). Always close everything in teardown:

import { test, after } from "node:test";
import { pool } from "../src/db.js";

// node:test runs `after` hooks once the file's tests complete
after(async () => {
  await pool.end();   // close the DB connection pool
  // if you started a listener, server.close() too
});

With supertest you usually don’t start a listener at all (it manages ephemeral ones), so the pool is the handle people forget. A hanging CI job that times out after ten minutes is almost always an unclosed pool or socket — not a slow test.