Integration and API Tests

Lesson 1 taught unit tests and test doubles. Lesson 2 tested UI components. Now we test the part in the middle: an HTTP API with a real database. We build a small notes API with Express, test it with supertest, and cover a test-database strategy, seeding, auth, contracts, webhooks, queues and speed.

This lesson does not repeat what other pages already cover. For the "unit, integration, contract" decision in a backend see Backend, Lesson 11. For Prisma-based database tests and tool reference see Full-Stack Lesson 21. For where integration tests sit in a frontend plan see Frontend Depth, Lesson 5. For the team-level test plan see Team Lead, Lesson 6. The next lesson, Lesson 4, moves to a real browser.

Words used in this lesson

• Integration test: a test that runs two or more real parts of your system together, for example the route handler plus the database. It does not need to cover the whole system.
• In-process: the app and the test run inside the same Node process. No separate server to start.
• Ephemeral port: a free port that the operating system picks for you when you ask for port 0.
• supertest: a library that sends HTTP requests to your app and gives you the response to check.
• Transaction rollback: a transaction is a group of database steps that succeed or fail together. A rollback undoes all of them. We can use it to wipe a test's changes.
• Contract: a written agreement about what a request and a response look like (names, types, required fields).
• Consumer-driven contract: a contract written by the caller (the consumer) of an API. It lists only the fields the caller really uses.
• OpenAPI: a standard file format (JSON or YAML) that describes the paths, inputs and outputs of an HTTP API.
• Webhook: an HTTP request that another service sends to you when something happens (for example "payment done").
• Idempotent: doing it twice has the same result as doing it once.
• Queue: a place where one part of the system puts messages and another picks them up later.

1. What "integration" means

The word is vague, so teams argue about it. Here is a working definition:

Three levels are common:

The rule I use: fake only what you do not own and cannot run cheaply (a payment provider, an email service). Keep real what you own and can run cheaply (your routes, your SQL, a local database). A fake database tells you nothing about your SQL. A real one tells you a lot.

2. The app under test

I wrote a small notes API. It has four things worth testing: bearer-token auth, validation, a per-user rule ("you only see your own notes"), and a webhook with a signature. It publishes a message to a queue when a note is created.

The key design choice is that createApp takes its dependencies as arguments (database, queue, clock, secret) and returns an Express app. It does not call listen. That one choice makes in-process testing easy.

// db.js (excerpt)import { DatabaseSync } from 'node:sqlite';export const SCHEMA = `  CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT UNIQUE NOT NULL, token TEXT UNIQUE NOT NULL);  CREATE TABLE notes (id INTEGER PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id),                      title TEXT NOT NULL, created_at TEXT NOT NULL);  CREATE TABLE payments (event_id TEXT PRIMARY KEY, user_id INTEGER NOT NULL, amount INTEGER NOT NULL);`;export function openDb(file = ':memory:') {  const db = new DatabaseSync(file);  db.exec('PRAGMA foreign_keys = ON');  db.exec(SCHEMA);  return db;}

// app.js (excerpt: the notes routes)export function createApp({ db, queue, webhookSecret, now = () => new Date() }) {  const app = express();  app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));  const auth = (req, res, next) => {    const m = /^Bearer (.+)$/.exec(req.get('authorization') ?? '');    const user = m && db.prepare('SELECT * FROM users WHERE token = ?').get(m[1]);    if (!user) return res.status(401).json({ error: 'unauthorized' });    req.user = user;    next();  };  app.post('/notes', auth, (req, res) => {    const title = req.body?.title;    if (typeof title !== 'string' || title.trim() === '') {      return res.status(400).json({ error: 'title is required' });    }    const info = db.prepare('INSERT INTO notes (user_id, title, created_at) VALUES (?, ?, ?)')      .run(req.user.id, title.trim(), now().toISOString());    queue.publish('note.created', { noteId: Number(info.lastInsertRowid), userId: req.user.id });    res.status(201).json({ id: Number(info.lastInsertRowid), title: title.trim() });  });  app.delete('/notes/:id', auth, (req, res) => {    const info = db.prepare('DELETE FROM notes WHERE id = ? AND user_id = ?').run(req.params.id, req.user.id);    res.status(info.changes ? 204 : 404).end();  });  // ... GET /notes and POST /webhooks/payment are in section 8  return app;}

3. Calling the app in-process with supertest

supertest takes your app and sends a real HTTP request to it. The supertest README says that if the server is not already listening, it "is bound to an ephemeral port for you", so you do not manage ports. You write the test like this:

// test/helpers.js (excerpt)export function fakeQueue() {  const messages = [];  return { messages, publish: (name, payload) => messages.push({ name, payload }) };}export function seedUser(db, email = 'ada@example.com', token = 'tok-ada') {  const { lastInsertRowid } = db.prepare('INSERT INTO users (email, token) VALUES (?, ?)').run(email, token);  return { id: Number(lastInsertRowid), email, token };}export function makeWorld() {            // a fresh app + fresh database + fake queue  const db = openDb();  const queue = fakeQueue();  const secret = 'whsec_test';  const app = createApp({ db, queue, webhookSecret: secret, now: () => new Date('2026-01-01T00:00:00Z') });  return { db, queue, secret, app };}

// test/notes.test.jsimport { test, describe, beforeEach } from 'node:test';import assert from 'node:assert/strict';import request from 'supertest';import { makeWorld, seedUser } from './helpers.js';describe('notes API', () => {  let w, ada;  beforeEach(() => { w = makeWorld(); ada = seedUser(w.db); });   // fresh DB for every test  test('rejects a request with no token', async () => {    const res = await request(w.app).get('/notes');    assert.equal(res.status, 401);  });  test('creates a note, stores it, and publishes an event', async () => {    const res = await request(w.app).post('/notes').set('Authorization', `Bearer ${ada.token}`)      .send({ title: '  Buy milk ' });    assert.equal(res.status, 201);    assert.deepEqual(res.body, { id: 1, title: 'Buy milk' });    const row = w.db.prepare('SELECT * FROM notes WHERE id = 1').get();    assert.equal(row.created_at, '2026-01-01T00:00:00.000Z');    assert.deepEqual(w.queue.messages, [{ name: 'note.created', payload: { noteId: 1, userId: ada.id } }]);  });  test('validates the body', async () => {    const res = await request(w.app).post('/notes').set('Authorization', `Bearer ${ada.token}`).send({ title: '  ' });    assert.equal(res.status, 400);    assert.equal(w.queue.messages.length, 0);          // nothing published on failure  });});

Look at what each test checks. The "creates a note" test checks four things at once: the HTTP answer, the stored row, the clock, and the message at the queue boundary. A unit test of the handler with a mocked database could never tell you that the SQL is right.

What to assert

Check the status code, the body shape, the side effects (rows, messages) and the non-effects on failure (a rejected request must not insert or publish). Assert headers only when they matter (Location, Set-Cookie).

The same test over a real socket

Sometimes you want a real socket, for example to test with fetch, a browser, or a client library. Ask for port 0 and read the port back:

before(async () => {  w = makeWorld(); seedUser(w.db);  server = w.app.listen(0);                       // port 0 = "OS, pick a free port"  await new Promise((r) => server.once('listening', r));  base = `http://127.0.0.1:${server.address().port}`;});after(() => server.close());test('real HTTP over a real socket with fetch', async () => {  const res = await fetch(`${base}/notes`, { method: 'POST',    headers: { authorization: 'Bearer tok-ada', 'content-type': 'application/json' },    body: JSON.stringify({ title: 'hello' }) });  assert.equal(res.status, 201);});

A fixed port like 3000 breaks as soon as two test files run at the same time, or a dev server is open. Port 0 never collides.

4. A test-database strategy

Every integration test needs a database in a known state. There are three common ways. All three ran in test/strategies.test.js.

const count = (db) => db.prepare('SELECT count(*) AS n FROM users').get().n;const add = (db, e) => db.prepare('INSERT INTO users (email, token) VALUES (?, ?)').run(e, 't-' + e);test('A. transaction rollback: undo everything after the test', () => {  const db = openDb();  db.exec('BEGIN');  add(db, 'a@x.io');  assert.equal(count(db), 1);  db.exec('ROLLBACK');                       // the "cleanup": one statement, very fast  assert.equal(count(db), 0);});test('B. truncate (delete in FK order) before each test', () => {  const db = openDb();  add(db, 'a@x.io');  for (const t of ['payments', 'notes', 'users']) db.exec(`DELETE FROM ${t}`);  assert.equal(count(db), 0);});test('C. a private database per test (fresh file or schema)', () => {  const dir = mkdtempSync(join(tmpdir(), 'dbtest-'));  const a = openDb(join(dir, 'a.db')), b = openDb(join(dir, 'b.db'));  add(a, 'a@x.io');  assert.equal(count(a), 1);  assert.equal(count(b), 0);                 // b never sees a's data: safe to run in parallel});

My default advice:

1. For SQLite, use :memory: per test (what makeWorld does). Opening a fresh in-memory database costs almost nothing.
2. For Postgres (not run here), create the schema once per test run, then clean with B or A between tests. If tests run in parallel, give each worker its own database or schema.
3. Never point tests at a shared development or staging database. Tests delete things.

5. Seeding data

Tests need rows. There are three ways to get them, from worst to best:

1. One big shared seed file. Every test depends on it, nobody dares to change it, and tests break when someone adds a row. Avoid it.
2. Inline SQL in each test. Clear, but noisy.
3. Small helper functions (a "factory"). Each test builds exactly what it needs. Defaults are filled in; the test overrides only what it cares about.

seedUser(db, email, token) above is a tiny factory. A good factory has three habits:

• It returns the created object (with its id), so the test does not guess.
• It gives each call unique default values when the column is unique. Fixed emails collide as soon as you create two users.
• It does not hide the thing the test is about. If the test is about "a user with no notes", it says so: seedUser(db) and no seedNote call.

Keep the data small. A test with 3 rows is easier to read and faster than a test with the whole production dump.

6. Testing auth

Auth bugs are the most expensive bugs an API can have, and unit tests rarely catch them. A short checklist, all in the same style:

The most important one is the third: an authenticated user must not touch another user's data. It has a name, "broken object-level authorization", and it is common in real APIs. Here is the test:

test("a user cannot see or delete another user's notes", async () => {  const bob = seedUser(w.db, 'bob@example.com', 'tok-bob');  await request(w.app).post('/notes').set('Authorization', `Bearer ${ada.token}`).send({ title: 'secret' });  const list = await request(w.app).get('/notes').set('Authorization', `Bearer ${bob.token}`);  assert.deepEqual(list.body, []);  const del = await request(w.app).delete('/notes/1').set('Authorization', `Bearer ${bob.token}`);  assert.equal(del.status, 404);  assert.equal(w.db.prepare('SELECT count(*) AS n FROM notes').get().n, 1);   // still there});

Notice the last line. A test that only checks 404 would pass even if the row had been deleted. Always check the data too. For cookie sessions, supertest offers request.agent(app), which keeps cookies between requests, like a browser does. For login in a browser, see storage state in Lesson 4.

7. Contract testing, explained simply

A contract answers one question: "If the server says it returns { id, title }, can the client trust that?" Two teams, one API, and one team renames title to name. Unit tests on both sides still pass. Production breaks. A contract test catches this earlier.

There are two common ways.

Way 1: validate responses against an OpenAPI schema (provider side)

The API's owner writes a schema (usually inside an OpenAPI file). A test calls the real endpoint and checks the response against the schema. I used ajv, a JSON Schema validator:

const openapi = { components: { schemas: { Note: {  type: 'object', required: ['id', 'title'], additionalProperties: false,  properties: { id: { type: 'integer' }, title: { type: 'string', minLength: 1 } } } } } };const validateNote = new Ajv().compile(openapi.components.schemas.Note);test('POST /notes response matches the Note schema', async () => {  const w = makeWorld(); const u = seedUser(w.db);  const res = await request(w.app).post('/notes').set('Authorization', `Bearer ${u.token}`).send({ title: 'x' });  assert.ok(validateNote(res.body), JSON.stringify(validateNote.errors));});

When I changed the response so title became name, the validator reported:

[["required","must have required property 'title'"]]

(That was a separate quick script that validated { id: 1, name: 'x' } against the same schema, not a change to the API.) The point is that the docs file and the code can no longer drift apart in silence. If you generate the OpenAPI file from the code, or the code from the file, the drift is smaller still. See tRPC, REST and OpenAPI for generating clients.

Way 2: consumer-driven contracts

Here the caller writes down what it needs: "I read id (number) and title (string). I do not care about anything else." The provider runs those expectations in its own tests. If the provider wants to remove title, a test fails before release, and it names the consumer who would break.

My toy version is only the idea:

const consumerExpects = { id: 'number', title: 'string' };const providerResponse = { id: 1, title: 'x', created_at: 'an extra field is fine' };for (const [k, type] of Object.entries(consumerExpects)) assert.equal(typeof providerResponse[k], type);

Real tools (the best known is Pact) store these expectations as files, share them between repositories, and check them on both sides. I did not run Pact, so I only describe it. Note the nice property: extra fields are fine, because the consumer only listed what it reads. That is why consumer-driven contracts let providers add fields safely, but warn them before they remove one.

8. Webhooks and queues: test at the boundary

Two systems talk through a boundary: an HTTP request from outside, or a message on a queue. The best place to test is exactly at that boundary, because that is where your code meets the outside.

Incoming webhook

A payment provider sends POST /webhooks/payment with a signature header. Your code must (1) check the signature, (2) handle duplicates, because providers retry. The handler:

app.post('/webhooks/payment', (req, res) => {  const expected = crypto.createHmac('sha256', webhookSecret).update(req.rawBody ?? '').digest('hex');  const given = req.get('x-signature') ?? '';  const ok = given.length === expected.length &&    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));  if (!ok) return res.status(401).json({ error: 'bad signature' });  const { id, userId, amount } = req.body;  const info = db.prepare('INSERT OR IGNORE INTO payments (event_id, user_id, amount) VALUES (?, ?, ?)')    .run(id, userId, amount);  res.status(200).json({ duplicate: info.changes === 0 });});

The tests sign the body the same way the provider does and send it twice:

test('rejects a wrong signature', async () => {  const res = await post(body, 'deadbeef');  assert.equal(res.status, 401);});test('accepts a valid signature and is idempotent', async () => {  const sig = sign(w.secret, body);  assert.deepEqual((await post(body, sig)).body, { duplicate: false });  assert.deepEqual((await post(body, sig)).body, { duplicate: true });   // provider retried  assert.equal(w.db.prepare('SELECT count(*) AS n FROM payments').get().n, 1);});

Outgoing queue

When POST /notes succeeds it publishes note.created. In tests the queue is a fake with the same interface: it records messages in an array. We assert that the message was published (success) and was not published (validation failure). That tests our side of the boundary.

What this does not prove: that the real broker accepts the message, or that the worker handles it. Cover those with:

• A separate unit or integration test of the worker: give it a message, check its effect. Queue messages are also a contract, so write the message shape down.
• A few real-broker tests (a Redis or RabbitMQ container) for the glue code only. I did not run a broker in this lesson.
• For the "write to database and publish a message" problem, which can lose messages, look up the outbox pattern. You test it by checking that the message row and the data row are saved together.

9. Running the whole suite

> t03@1.0.0 test> node --test --test-reporter=spec test/*.test.js✔ POST /notes response matches the Note schema (67.597038ms)✔ consumer-driven contract: what the web client reads (0.375365ms)▶ notes API  ✔ rejects a request with no token (33.600641ms)  ✔ creates a note, stores it, and publishes an event (17.826821ms)  ✔ validates the body (8.768989ms)  ✔ a user cannot see or delete another user's notes (22.627347ms)✔ notes API (84.291922ms)port used: true | status: 201✔ real HTTP over a real socket with fetch (85.053442ms)✔ A. transaction rollback: undo everything after the test (13.195698ms)✔ B. truncate (delete in FK order) before each test (0.646898ms)✔ C. a private database per test (fresh file or schema) (55.29625ms)▶ payment webhook  ✔ rejects a wrong signature (38.38613ms)  ✔ accepts a valid signature and is idempotent (14.084848ms)✔ payment webhook (53.483506ms)ℹ tests 12ℹ pass 12ℹ fail 0ℹ duration_ms 801.919821

Twelve tests, real routes, real SQL, real signatures, in about 0.8 seconds on this machine (the whole node --test process took 0.78 s wall time, including start-up). The first test in each file is slower (module loading, first request): 30 to 70 ms. Later requests take 10 to 25 ms.

10. Speed tips

Slow integration tests get skipped, so speed is a feature.

1. Build the app once per file, reset data per test. Creating the app is cheap here, but a real app may load config, connect to a pool and run migrations. Do that in before, not beforeEach.
2. Run migrations once per run, not once per test. Keep the schema in a template database and copy it.
3. Use rollback or truncate for cleanup, not drop-and-recreate.
4. Run files in parallel, tests inside a file in series. The Node runner runs separate test files in separate processes at the same time, and the number is controlled by --test-concurrency. Parallel files need separate databases (strategy C) or separate schemas.
5. Fake only slow, outside things: the network, the clock (use a fake you control), the email provider. Keep your own database real.
6. Do not log in through the UI in an API test. Insert a user with a token (like seedUser) and send the header.

Try it

1. Add a PATCH /notes/:id that changes the title. Write four tests: no token, someone else's note, empty title, success. Answer: the "someone else's note" test must also check the row is unchanged.
2. Break the WHERE user_id = ? in DELETE /notes/:id on purpose. Which test fails? Answer: "a user cannot see or delete another user's notes". If none fails in your project, you found a missing test.
3. Change strategy A (rollback) so the handler opens its own database connection. Why does the cleanup stop working? Answer: a rollback only undoes work done on the same connection that ran BEGIN.

Interview questions

Key takeaways

• An integration test uses several of your own real parts together and fakes only the outside world.
• Build the app with a function that takes its dependencies (database, queue, clock). Do not call listen in it. Then supertest or listen(0) is enough.
• Give every test a known database state: rollback, truncate, or a private database. Use the same engine as production when you can.
• Seed with small factory functions, not one giant file.
• Test auth with the cross-user case, and always check the data as well as the status code.
• Contracts stop two teams from drifting apart: OpenAPI validation for the provider, consumer-driven contracts for known callers.
• Test webhooks and queues at the boundary: signature, duplicates, published messages. Test workers separately.
• Speed comes from doing set-up once, cheap cleanup, parallel files and small data.

What's next

Lesson 4: End-to-End Tests with Playwright, and Fixing Flaky Tests takes the same ideas into a real browser: when it is worth the cost, how to write tests that do not flake, and how to fix the ones that do.