AGENT SKILL

oak-tdd

Builds a change test first, writing a failing test for each small piece of behaviour, making it pass with the simplest code, then tidying up, and adds tests to existing code before changing it. Use when asked to use TDD or write tests first, to add or improve tests, or to fix a bug with a test that proves the fix.

License 许可
MIT
最近更新
2026-11-11
Stars
★ 0
Forks
1

01 前言 Front Matter

name
oak-tdd
license
MIT
metadata
{ "owner": "@oaknational/skills-maintainers", "updated": "2026-10-27" }
description
Builds a change test first, writing a failing test for each small piece of behaviour, making it pass with the simplest code, then tidying up, and adds tests to existing code before changing it. Use when asked to use TDD or write tests first, to add or improve tests, or to fix a bug with a test that proves the fix.

03 SKILL.md 正文

Test-driven development

Write the test before the code it tests, one small behaviour at a time. A test you haven't seen fail proves nothing: it might pass whatever the code does.

Before you start

  1. Read the repository's AGENTS.md for its test commands, including how to run a single test file, and where tests live.
  2. Read the tests next to the code you're changing. Match their framework, helpers, fixtures and naming. Don't add a new test library without asking.
  3. Run the existing tests for that area, so you know the starting point. If any already fail, tell the user before you change anything.
  4. Turn the request, or the ticket's acceptance criteria, into a short list of behaviours to build, simplest first. Show the list to the user before writing code.

The loop

Work through the list one behaviour at a time.

  1. Red. Write one test for the next behaviour, then run it. Check that it fails, and for the reason you expect: read the failure message. A missing import or a syntax error isn't the failure you're looking for.
  2. Green. Write the simplest code that makes the test pass. Run the test, then the rest of the test file.
  3. Refactor. With every test passing, tidy the code and the tests: remove duplication, improve names, and simplify. Run the tests again.
  4. Cross the behaviour off the list, and add any new cases you've noticed.

Don't write code that no failing test needs, and don't write several tests before any code. Write the next test only once the last one passes, so it can build on what you've just learned. If a step takes more than a few minutes, the step is too big: undo it and write a smaller test.

Writing good tests

  • Test behaviour, not implementation. Call the code the way its users do, through its public interface, so you can refactor without breaking the tests. Check results through that interface too, not by a back door such as querying the database directly, and don't assert how often or in what order internal code is called.
  • One behaviour per test. Name the test after the behaviour and its result, such as "returns 0 for an empty basket".
  • Arrange, act, assert. Set up the inputs, call the code once, then check the result, using realistic values.
  • Work out each expected value by hand, from the requirement or an example you've checked, and write it as a fixed value. If the test calculates it the same way the code does, it will pass even when the code is wrong.
  • Cover the edges. Empty inputs, boundaries, invalid input, and failures from the code's dependencies, wherever the requirement implies them.
  • Replace only what you don't control. Use test doubles for the network, other services, the clock and randomness. Use the real code for everything else and, where the repository has a test database, use it rather than a fake.
  • Keep tests independent and repeatable. No waiting for fixed times, no reliance on test order, and no state shared between tests.
  • Pick the right level. Unit tests for logic, integration tests for how parts fit together, and end-to-end tests only for the few journeys that matter most. Follow the levels the repository already uses.
  • For an interface, find elements the way people do, by their role and label, rather than by class names or test IDs.

Adding tests to existing code

Before changing code that has no tests, write tests that pin down what it does now. They should pass straight away, and they become the safety net for your change.

A test that passes as soon as you write it hasn't been proved. Break the code briefly, for example by changing a return value, watch the test fail, then undo the break.

Fixing a bug

Write a test that reproduces the bug first, and check it fails in the way the bug report describes. Then fix the bug and watch the test pass. Keep the test, so the bug can't come back unnoticed.

Rules

  • Never weaken or delete an assertion, or skip a test, to make the tests pass. If the code can't pass a fair test, tell the user.
  • Don't change a test and the code it checks in the same step, except while refactoring with every test passing.
  • Coverage is a side effect, not the goal. Don't add tests only to raise a number.
  • Before you say the work is finished, run the whole test suite, the type check and the linter, using the commands in AGENTS.md.

Report

  • The behaviours you built, each with its test name and location, such as src/basket.test.ts:42.
  • For each new test, one line on how it failed before it passed.
  • Which commands you ran at the end, and their results.
  • Anything left untested, and why.

04 同仓库更多 Skills