JS-230 · Lesson 10 of 12 · 32 min

Testing APIs

▶ Video coming soon A video version of this lesson is on the way.

On Thursday, April 6, the partner service has nine routes, four middleware functions and a set of kitchen rules, and Mira has tested all of it by hand with curl. Then she changes the cut-off code to fix a message, and Rosa's test order for a Monday goes through on a Sunday afternoon. Nobody notices until Gareth runs the test script he wrote in the morning. "In JS-210 you tested the counter page," he says. "A server needs tests even more, because nobody watches it, and its mistakes reach three agencies and a kitchen before you hear about them."

This lesson tests a back end at the right levels. It uses Node's built-in test runner, node:test, with node:assert, so the tests need no packages. It starts with unit tests of the kitchen's rules, using table-driven cases. It shows how to build the app with a function that takes its dependencies, the repository and the clock, so tests can pass in fakes. It then tests the API over real HTTP on a random port with fetch, introduces supertest for the Express app, and explains where tests against a real PostgreSQL database fit. By the end, the bug that let a Sunday order through is caught in under a second.

What to test, and at which level

JS-210 introduced the testing pyramid: many fast unit tests at the bottom, fewer integration tests in the middle and a handful of slow end-to-end tests at the top. For an API the levels map neatly onto the layers of the service.

Test levels for the partner service
LevelWhat it testsExample in the partner serviceSpeed
UnitOne function, no network or databasecheckRules, cutoffFor, mergePatch, the validatorMicroseconds
IntegrationA layer with its real dependencyorders-repo.js against a test PostgreSQL databaseMilliseconds
APIThe app over HTTP, with fakes behind itPOST /orders gives 201, 401, 409 or 422Milliseconds
End-to-endEverything, as a user would use itThe partners' form placing a real order (Playwright)Seconds

Most of the service's important behavior is in its rules, its validation and the way routes turn results into status codes, so most tests are unit and API tests. The repository's locking and the database constraints need integration tests, because only a real database shows whether two transactions wait for each other.

A pyramid with four levels. At the bottom, many unit tests of rules and validation. Above, API tests over HTTP with fakes. Above that, integration tests of the repository against PostgreSQL. At the top, a few end-to-end tests of the partners form. An arrow along the side points up, labeled slower and fewer.
Test levels for the partner service: many fast tests at the bottom, a few slow ones at the top.

How a test runner works

A test runner collects named test functions, runs each one, and reports which passed and which failed. An assertion is a check inside a test that throws if something is not as expected; a test that throws fails, and a test that finishes passes. The example builds a tiny runner with two assertions to show that nothing magical is involved.

JavaScript Example · A tiny test runner
const tests = [];
const test = (name, fn) => tests.push({ name, fn });
const assert = {
  equal(actual, expected) {
    if (actual !== expected) throw new Error(`expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
  },
  deepEqual(actual, expected) {
    if (JSON.stringify(actual) !== JSON.stringify(expected)) throw new Error(`expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
  },
};

async function run() {
  let failed = 0;
  for (const t of tests) {
    try { await t.fn(); console.log('ok    ', t.name); }
    catch (err) { failed++; console.log('FAILED', t.name, '-', err.message); }
  }
  console.log(`${tests.length - failed} passed, ${failed} failed`);
}

const traysOf = (order) => order.lines.reduce((s, l) => s + l.trays, 0);
test('adds the trays of every line', () => assert.equal(traysOf({ lines: [{ trays: 4 }, { trays: 2 }] }), 6));
test('an order with no lines has 0 trays', () => assert.equal(traysOf({ lines: [] }), 0));
test('lists items in order', () => assert.deepEqual(['soup', 'stew'].sort(), ['soup', 'stew']));
test('this one is wrong on purpose', () => assert.equal(traysOf({ lines: [{ trays: 3 }] }), 4));
await run();
Output
ok     adds the trays of every line
ok     an order with no lines has 0 trays
ok     lists items in order
FAILED this one is wrong on purpose - expected 4, got 3
3 passed, 1 failed

What this code does

test only records a name and a function, and run calls each function inside try...catch, printing ok if it finishes and FAILED with the message if an assertion throws. The assertions compare values and throw an Error with a message that shows both the expected and actual values, which is what makes a failing test useful. The last test fails on purpose to show the report.

node:test and node:assert

Node has its own test runner, node:test, stable since Node 20, and an assertion library, node:assert. node --test finds files whose names end in .test.js, .test.mjs or similar, runs each in its own process and reports the results. Tests are written with test(name, fn), grouped with describe, and can share set-up with before, after, beforeEach and afterEach. The strict version of assert, node:assert/strict, compares with === and checks deep equality including types, which avoids surprises such as 1 == '1'.

The first tests are for the rules. Table-driven tests, a list of cases and one loop that turns each into a test, suit rules like these well: adding a case is one line, and the case list reads like a specification Rosa could check.

JavaScript Example · Unit tests for the rules
// test/rules.test.mjs
import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
import { cutoffFor, checkRules } from '../src/rules.js';

describe('cutoffFor', () => {
  test('a Monday delivery closes on Saturday at noon', () => {
    assert.equal(cutoffFor('2028-04-10'), '2028-04-08T12:00');
  });
  test('works across the end of a month', () => {
    assert.equal(cutoffFor('2028-05-01'), '2028-04-29T12:00');
  });
});

describe('checkRules', () => {
  const cases = [
    { date: '2028-04-12', now: '2028-04-10T11:59', want: [] },
    { date: '2028-04-12', now: '2028-04-10T12:00', want: ['cut-off passed'] },
    { date: '2028-04-11', now: '2028-04-01T09:00', want: ['not a delivery day'] },
    { date: '2028-04-09', now: '2028-04-08T09:00', want: ['not a delivery day', 'cut-off passed'] },
  ];
  for (const c of cases) {
    test(`${c.date} at ${c.now}`, () => {
      assert.deepEqual(checkRules(c.date, c.now), c.want);
    });
  }
});

What this code does

describe groups related tests and test defines each one with a name that says what should be true. assert.equal and assert.deepEqual compare the result with what is expected, and each case in the table becomes a test named after its date and time. The run checks noon exactly, a minute before noon, a non-delivery day and a case where both rules fail.

Running it
$ node --test --test-reporter=spec
▶ cutoffFor
  ✔ a Monday delivery closes on Saturday at noon
  ✔ works across the end of a month
✔ cutoffFor
▶ checkRules
  ✔ 2028-04-12 at 2028-04-10T11:59
  ✔ 2028-04-12 at 2028-04-10T12:00
  ✔ 2028-04-11 at 2028-04-01T09:00
  ✔ 2028-04-09 at 2028-04-08T09:00
✔ checkRules
ℹ tests 6
ℹ suites 2
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 41.2

The spec reporter prints a tree of passing tests and a summary. When a test fails, it prints the assertion's message with the expected and actual values and the line of the test. The test that would have caught Mira's bug is the second checkRules case: at 12:00 exactly, the cut-off has passed. Her change had turned >= into >.

Building the app so it can be tested

The service's handlers use two things that make testing hard: the database and the clock. Tests should not need a running PostgreSQL to check a status code, and they certainly should not depend on what time it is when someone runs them, or the cut-off tests would pass on Mondays and fail on Saturdays. The fix is dependency injection: instead of importing the repository and calling the real clock directly, the app is built by a function, createApp, that receives them as arguments. Production passes the real ones; tests pass fakes.

JavaScript Example · Injecting the clock and the repository
function createHandler({ repo, now }) {
  return async function handle(req) {
    const date = req.body?.deliveryDate;
    if (!date) return { status: 422, body: { title: 'deliveryDate is required' } };
    const cutoff = new Date(Date.parse(date + 'T12:00:00Z') - 2 * 86_400_000).toISOString().slice(0, 16);
    if (now() >= cutoff) return { status: 409, body: { title: 'cut-off passed', cutoff } };
    return { status: 201, body: await repo.create(req.body) };
  };
}

// Fakes for a test: a clock we control and a repository that records what it saves.
let clock = '2028-04-05T11:59';
const saved = [];
const fakeRepo = { async create(o) { saved.push(o); return { id: saved.length, ...o }; } };
const handle = createHandler({ repo: fakeRepo, now: () => clock });

console.log(await handle({ body: { deliveryDate: '2028-04-07' } }));
clock = '2028-04-05T12:00';
console.log(await handle({ body: { deliveryDate: '2028-04-07' } }));
console.log(await handle({ body: {} }));
console.log('saved', saved.length, 'order(s)');
Output
{ status: 201, body: { id: 1, deliveryDate: "2028-04-07" } }
{ status: 409, body: { title: "cut-off passed", cutoff: "2028-04-05T12:00" } }
{ status: 422, body: { title: "deliveryDate is required" } }
saved 1 order(s)

What this code does

createHandler takes its two dependencies as arguments instead of reaching for the real database and the real time. The test passes a clock that it can set to any moment and a repository that keeps orders in an array, so it can check one minute before noon and noon exactly in the same run. It can also check that refused requests saved nothing, which would be hard to see from outside a real database.

In the partner service, src/app.js exports createApp({ repo, clock, partners, logger }), and src/server.js, the only file that knows about the real world, builds the real dependencies from the config and passes them in. The same function makes the service easy to run locally against the in-memory repository from Lesson 7, which Mira uses when she wants to try something without a database.

Testing over real HTTP

API tests send real HTTP requests to the app and check the responses: the status code, important headers and the body. The app is started on port 0, which asks the operating system for any free port, so tests never clash with a server already running and several test files can run at once. before starts the server, after closes it, and beforeEach resets the fakes so each test starts clean. The example uses a node:http version of the app so that it runs with nothing installed.

JavaScript Example · API tests on a random port
// test/orders.api.test.mjs
import { test, before, after, beforeEach } from 'node:test';
import assert from 'node:assert/strict';
import { createApp } from '../src/app.js';

let server, base, clock, saved;
const repo = { async create(partner, body) { const o = { id: saved.length + 1, partner, ...body }; saved.push(o); return o; } };

before(async () => {
  server = createApp({ repo, now: () => clock, partners: { 'test-key-n': 'northside' } });
  await new Promise((resolve) => server.listen(0, resolve)); // port 0: any free port
  base = `http://127.0.0.1:${server.address().port}/api/partners/v1`;
});
after(() => server.close());
beforeEach(() => { saved = []; clock = '2028-04-03T09:00'; });

const post = (body, key = 'test-key-n') => fetch(`${base}/orders`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
  body: JSON.stringify(body),
});

test('places an order before the cut-off', async () => {
  const res = await post({ deliveryDate: '2028-04-07', lines: [{ item: 'soup', trays: 4 }] });
  assert.equal(res.status, 201);
  assert.equal((await res.json()).partner, 'northside');
  assert.equal(saved.length, 1);
});

test('refuses an order after the cut-off and saves nothing', async () => {
  clock = '2028-04-05T12:00';
  const res = await post({ deliveryDate: '2028-04-07', lines: [{ item: 'soup', trays: 4 }] });
  assert.equal(res.status, 409);
  assert.match((await res.json()).detail, /cut-off/);
  assert.equal(saved.length, 0);
});

test('refuses an unknown key with 401', async () => {
  const res = await post({ deliveryDate: '2028-04-07', lines: [] }, 'nope');
  assert.equal(res.status, 401);
});

What this code does

before builds the app with a fake repository, a controllable clock and one test key, and starts it on a free port; after closes it so the test process can exit. Each test sends a real POST with fetch and checks the status code, part of the body and what the fake repository saved. The second test moves the clock to the cut-off and checks both the 409 and that nothing was stored.

Running it
$ node --test --test-reporter=spec test/orders.api.test.mjs
✔ places an order before the cut-off
✔ refuses an order after the cut-off and saves nothing
✔ refuses an unknown key with 401
ℹ tests 3
ℹ suites 0
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 97.5

Testing the cut-off at the exact second is only possible because the clock is injected. The test for 401 shows the other principle of API tests: check the failure cases as carefully as the successes. Most real bugs in an API are a missing check, a wrong status code or an error that leaks into a 500, and only tests of the unhappy paths find them.

supertest for Express

For the Express app, the studio uses supertest, a package that takes an app, starts it on a temporary port for each request and offers a fluent way to send requests and check responses. Its expect methods check the status code and headers, and the response body is already parsed. With createApp, each test gets a fresh app with an in-memory repository and a fixed clock.

JavaScript Example · Testing the Express app with supertest
// test/orders.express.test.js — the Express app with supertest
import { test, beforeEach } from 'node:test';
import assert from 'node:assert/strict';
import request from 'supertest';
import { createApp } from '../src/app.js';
import { createMemoryRepo } from './helpers/memory-repo.js';

let app, repo;
beforeEach(() => {
  repo = createMemoryRepo({ capacity: 40 });
  app = createApp({ repo, clock: () => '2028-04-03T09:00', partners: testPartners });
});

test('a retried POST with the same Idempotency-Key creates one order', async () => {
  const send = () => request(app).post('/api/partners/v1/orders')
    .set('Authorization', 'Bearer test-key-n').set('Idempotency-Key', 'k-1')
    .send({ deliveryDate: '2028-04-07', lines: [{ item: 'soup', trays: 4 }] });
  const first = await send().expect(201);
  const second = await send().expect(201);
  assert.equal(second.body.id, first.body.id);
  assert.equal((await repo.listForDay('2028-04-07')).length, 1);
});

test('Northside cannot read an Elm Street order', async () => {
  const order = await repo.create(elmStreet.id, { deliveryDate: '2028-04-07', lines: [{ item: 'stew', trays: 2 }] });
  await request(app).get(`/api/partners/v1/orders/${order.id}`)
    .set('Authorization', 'Bearer test-key-n')
    .expect(404)
    .expect('Content-Type', /application\/problem\+json/);
});

What this code does

request(app) needs no running server: supertest starts the app for the request and stops it afterwards. The first test sends the same POST twice with one Idempotency-Key and checks that both answers carry the same id and that only one order was stored. The second creates an order for Elm Street directly in the repository and checks that Northside's key gets a 404 in problem details format, not the order.

These two tests protect properties that matter far more than any single field: an agency's retry never creates a duplicate, and one agency can never see another's order. The studio's rule is that every rule Rosa or Theo has asked for has at least one test named after it, so a failing test explains itself in the words of the person who asked.

Tests against a real database

The repository's SQL, its transactions and its locks can only be tested against PostgreSQL itself. The service's integration tests use a separate test database that is created fresh in CI from the same migrations as production, and is emptied between tests, either by deleting all rows or by running each test inside a transaction that is rolled back at the end. The test for Gareth's race starts two transactions that order the last trays for the same day at the same time, with Promise.all, and checks that exactly one succeeds.

JavaScript Example · An integration test for the race
test('two orders for the last trays: exactly one succeeds', async () => {
  await setCapacity('2028-04-12', 4);
  const results = await Promise.allSettled([
    repo.create(northside.id, { deliveryDate: '2028-04-12', lines: [{ item: 'soup', trays: 4 }] }),
    repo.create(elmStreet.id, { deliveryDate: '2028-04-12', lines: [{ item: 'stew', trays: 4 }] }),
  ]);
  assert.deepEqual(results.map((r) => r.status).sort(), ['fulfilled', 'rejected']);
  assert.match(results.find((r) => r.status === 'rejected').reason.message, /0 trays left/);
  assert.equal(await traysOrdered('2028-04-12'), 4);
});

What this code does

The test sets Wednesday's capacity to 4 trays and sends two orders of 4 trays at the same moment through the real repository and database. Promise.allSettled waits for both whatever happens, and the test checks that one was accepted and one refused with the capacity message. The last assertion reads the database to confirm that the day really holds 4 trays, not 8.

In CI, GitHub Actions starts a PostgreSQL container as a service for the test job, runs the migrations against it and then runs node --test. The same tests run on Mira's laptop against a local PostgreSQL. The SQLite version of the repository from Lesson 7 is not used for these tests, because it does not have FOR UPDATE and would pass for the wrong reason.

Fakes, mocks and spies

The fake repository above is a fake: a simple working replacement. Sometimes a test needs to know how a function was used rather than what it did, for example that the reminders script called the mail queue's upload once per batch, never once per message. A mock function, also called a spy, records every call with its arguments. node:test provides mock.fn() for this, and mock.timers to control setTimeout and Date in tests.

JavaScript Example · A spy records how it was called
function mockFn(impl = () => undefined) {
  const calls = [];
  const fn = (...args) => { calls.push(args); return impl(...args); };
  fn.calls = calls;
  return fn;
}

async function sendBatch(messages, upload) {
  if (messages.length === 0) return 0;
  await upload(`reminders-${messages[0].date}.json`, messages);
  return messages.length;
}

const upload = mockFn(async () => 'ok');
console.log(await sendBatch([{ date: '2028-04-07', to: 'amara' }, { date: '2028-04-07', to: 'ben' }], upload));
console.log(await sendBatch([], upload));
console.log('upload called', upload.calls.length, 'time(s)');
console.log('first call:', upload.calls[0][0], 'with', upload.calls[0][1].length, 'messages');
Output
2
0
upload called 1 time(s)
first call: reminders-2028-04-07.json with 2 messages

What this code does

mockFn wraps an implementation and records the arguments of every call in its calls array. The test can then check that sendBatch called upload exactly once for a batch of two messages, with the right file name, and not at all for an empty batch. node:test's mock.fn() works the same way and also records return values and errors.

Mocks are useful but easy to overuse. A test that checks every internal call breaks whenever the code is reorganized, even if its behavior is the same. The studio prefers tests that check results, such as a response or a row in the database, and uses spies only for effects that cannot be seen otherwise, such as messages sent to another system.

Running tests in CI

The service's package.json has npm test run node --test, and the GitHub Actions workflow from JS-210 runs it, with the database service, on every push and pull request. node --test --experimental-test-coverage also reports which lines the tests ran, which helps find untested branches, such as an error path nobody wrote a test for. Theo's review rule is simple: a pull request that changes a rule or a route without changing a test needs a reason in its description.

Worked problem

How long does the test suite take?

The service has 140 unit tests at about 0.2 ms each, 45 API tests at about 6 ms each and 18 database integration tests at about 40 ms each, plus 2.5 s to start the database container and run the migrations in CI. How long does a full run take, and how long without the database part on a laptop?

Show solution
  1. Unit: 140 × 0.2 = 28 ms.
  2. API: 45 × 6 = 270 ms.
  3. Integration: 18 × 40 = 720 ms.
  4. CI total: 0.028 + 0.27 + 0.72 + 2.5 ≈ 3.5 s.
  5. Without the database part: 0.028 + 0.27 ≈ 0.3 s.

Answer: About 3.5 seconds in CI and 0.3 seconds for the unit and API tests alone, which is why Mira runs those on every save with node --test --watch and leaves the database tests to CI.

Common mistakes

  • MistakeTests should use the real clock.

    InsteadInject the clock, so cut-off tests can check exact moments and give the same result every day.

  • MistakeTesting only the successful requests is enough.

    InsteadMost API bugs are in the failure paths: missing checks, wrong status codes and errors that become 500s.

  • MistakeAn in-memory repository proves the database locking works.

    InsteadOnly a test against the real database can show that two transactions wait for each other.

  • MistakeA test server should listen on port 3000.

    InsteadUse port 0 to get any free port, so tests never clash with other servers or each other.

Summary and key terms

  • A back end is tested at several levels: unit tests for rules and validation, API tests over HTTP with fakes behind the app, integration tests of the repository against a real test database and a few end-to-end tests. node:test provides test, describe, set-up hooks, mocks and a runner started with node --test, and node:assert/strict provides strict assertions.
  • Table-driven tests turn a list of cases into tests.
  • Building the app with createApp, which receives the repository, the clock and other dependencies, lets tests pass in fakes and test exact moments such as the cut-off.
  • API tests start the app on port 0 and use fetch, or supertest for Express, and check failure cases as carefully as successes.
  • Database tests run against a fresh test database in CI, including a test that two simultaneous orders cannot both take the last trays.
  • Spies record calls for effects that cannot be seen otherwise.
node:test
Node's built-in test runner, started with node --test.
Assertion
A check in a test that throws if a value is not as expected.
Table-driven test
A list of input and expected-output cases turned into tests by one loop.
Dependency injection
Passing a component the things it depends on, such as a clock or repository, instead of letting it create them.
Fake
A simple working replacement for a real dependency, such as an in-memory repository.
Spy
A function that records how it was called; also called a mock function.
Port 0
A request to the operating system for any free port.
supertest
A package for sending HTTP requests to an Express app in tests and checking the responses.
Test database
A separate database, built from the same migrations, used only by tests.

Practice problems

Work each problem on paper first, then reveal the answer to check.

  1. Which level of test would catch a wrong status code for an unknown API key?

    Show answer

    An API test.

  2. Why does createApp take now as an argument?

    Show answer

    So tests can set the time to any moment, such as exactly the cut-off.

  3. Why do API tests listen on port 0?

    Show answer

    To get any free port, so they never clash with other servers or tests.

  4. Why must the race test run against PostgreSQL rather than SQLite or the memory repository?

    Show answer

    Only PostgreSQL has the row locks the code relies on, so only it can show they work.

  5. When is a spy better than checking a result?

    Show answer

    When the effect cannot be seen otherwise, such as a message sent to another system.

Try it yourself

Write a deep equality check

Complete deepEqual(a, b) so that it returns true when two values are equal in the way a test needs: numbers, strings, booleans and null by ===; arrays when they have the same length and equal elements in the same order; plain objects when they have the same keys (in any order) with equal values.

Anything else, such as an array compared with an object, is not equal.

function deepEqual(a, b) {
  return JSON.stringify(a) === JSON.stringify(b);
}

console.log(deepEqual({ item: 'soup', trays: 4 }, { trays: 4, item: 'soup' }));
console.log(deepEqual([1, [2, 3]], [1, [2, 3]]));
console.log(deepEqual([1, 2], [2, 1]));
console.log(deepEqual({ a: 1 }, { a: 1, b: undefined }));
console.log(deepEqual([], {}));
console.log(deepEqual({ lines: [{ trays: 2 }] }, { lines: [{ trays: '2' }] }));
console.log(deepEqual(null, {}));

Try it yourself

Record calls with a spy

Complete spy(impl) so that it returns a function that calls impl with the same arguments and returns its result, while recording each call. The returned function has a calls array of argument lists and a results array of return values.

If impl throws, record { error: message } in results and throw the error again.

function spy(impl) {
  const fn = (...args) => impl(...args);
  fn.calls = [];
  fn.results = [];
  return fn;
}

const trays = spy((order) => {
  if (!Array.isArray(order.lines)) throw new Error('no lines');
  return order.lines.reduce((s, l) => s + l.trays, 0);
});
console.log(trays({ lines: [{ trays: 4 }, { trays: 2 }] }));
try { trays({}); } catch (err) { console.log('threw:', err.message); }
console.log(trays.calls.length, JSON.stringify(trays.results));

Lesson quiz · 5 questions

Score 60% or more to complete this lesson.

Take the quiz