Skip to content
Hands-on Coding Assistants

Part 4 — Build the Harness Chapter 12

Focused Tests and Coverage Gates

In this chapter

The registration bug took two requests to see. One request returned the expected 400. The next one exposed the consumed ID. You need an HTTP test for that sequence. A pure validator gives you a cheaper way to test how the application handles types, whitespace, and boundary lengths.

Start from lab-registration, the known-good reference for the registration change. Bring the regression test you wrote during debugging, or read the reference in lab-coverage.

git switch -c coverage-exercise lab-registration
npm test
npm run test:registration
git show lab-coverage:test/registration-regression.test.ts

Give each test one job

Ask Plan to read the registration spec, src/app.ts, and the HTTP tests. Give it the failure you reproduced. Then ask Build to extract a pure normalizeRegistration(input: unknown) function into src/registration.ts and test that function in test/registration.test.ts. Keep the response mapping and ID allocation in the route.

Extract the registration input validation without changing the HTTP API.
Add focused tests for a valid name and email that need normalization, a
non-string name, and a name at the 100-character limit. Keep the HTTP
contract unchanged. Use the HTTP helper to check that a rejected request
leaves ID 1 available on a fresh server.

Check a separate pair of HTTP tests around the task title limit in test/app.test.ts. A title with 120 characters is valid. A title with 121 returns 400 and leaves the list unchanged. Assert the full result and compare state where it matters.

test("a title over the limit leaves tasks unchanged", async t => {
  const request = await startApp(t);
  const before = await (await request("/tasks")).json();
  const response = await request("/tasks", jsonRequest("POST", {
    title: "x".repeat(121),
  }));
  assert.equal(response.status, 400);
  assert.deepEqual(await response.json(), { error: "invalid_task" });
  assert.deepEqual(await (await request("/tasks")).json(), before);
});

With the new tests in place, temporarily change the title check from > 120 to >= 120 in your exercise branch. npm test should fail on the exact-limit case with an observed 400 where it expected 201. Undo that edit and rerun both suites. If the test stays green with the fault in place, find out which input it sends and which code it reaches before accepting it.

Read the failure from the coverage command

Run this command in a separate worktree at lab-start, using Node 24.22.3, the version in .nvmrc. Check node --version and select that release before measuring. Its three tests can all pass while the command exits unsuccessfully because it also requires 90% line coverage of src/app.ts.

git worktree add --detach ../task-api-coverage-probe lab-start
cd ../task-api-coverage-probe
node --test --experimental-test-coverage --test-coverage-lines=90 \
  --test-coverage-include=src/app.ts test/*.test.ts

Read the uncovered lines in the report. Find a case you would want to protect anyway, such as a body that’s too large to parse. Send the request and assert the response and untouched state. Repeat the report on the same Node version and file selection. A different runtime or selection can change the number you are comparing.

Enforce the versioned policy

From the probe worktree, use lab-coverage to create a separate checkpoint for the rest of the exercise. It includes the focused unit and HTTP cases, coverage-policy.json, and tools/coverage.mjs.

git worktree add -b coverage-policy-exercise ../task-api-coverage-policy lab-coverage
cd ../task-api-coverage-policy
npm run coverage
npm run verify
node tools/coverage.mjs --base "$(git rev-parse lab-coverage)"

Open the policy and compare the report with its file list and the covered and total counts for each minimum. On Node 24.22.3, the checkpoint measures 81 of 83 lines, 43 of 46 branches, and all five functions across the included files. npm run coverage gives you the measurement. npm run verify checks it against the policy.

Temporarily remove the test named “an unknown path returns the not_found response” from test/app.test.ts in this clean exercise branch. npm test still passes. npm run verify fails on coverage. Read the new line and branch ratios before restoring that test from HEAD. This shows why you need the gate even after the test runner reports green.

The base comparison also checks the proposed policy against the starting revision. Try lowering the line minimum’s covered count in coverage-policy.json. Run the base check again and read the rejection. Restore the policy from HEAD. Policy changes need someone to review why the measurement or minimum is changing. When you accept a higher measured coverage ratio, raise the corresponding minimum so the next change preserves the improvement.

Keep the command and the failing check alongside your exercise diff. The next chapter gives that command its own checkout and a place in the merge rules.

References