Test-driven development with an AI coding assistant

Read a sample · Chapter 01 of 06

Before asking an assistant to write code, decide how you will recognise correct behaviour. A short, explicit contract gives you something independent of the generated implementation to test.

This lab calculates a fictional delivery fee. Its values are teaching inputs, not a real merchant policy or Mickai pricing. The function accepts a subtotal in integer pence and a Boolean express flag, then returns only the delivery fee in integer pence. It does not calculate the basket total, collect payment or decide whether a real order can be shipped. That small boundary lets us inspect every decision.

Scroll sideways to see every column.

The threshold includes exactly 5,000. Express remains paid even above it. Zero is a valid calculation input here; that does not mean a checkout must accept an empty basket. Keep application policy separate from this deliberately narrow function. Strings, floats and Boolean subtotals are rejected rather than converted. Invalid input must not look like a legitimate free-delivery result.

Examples are an executable interpretation of this contract. A test oracle is the reason an expected answer is correct. Here that reason is the written table and arithmetic, not whatever value the function currently returns. If you copy expected results from a generated implementation, both can share the same mistake. Resolve an ambiguous requirement before turning it into a permanent assertion.

Use a new practice directory and Python 3.12 for the recorded environment. The checked run used Python 3.12.10 on Windows 11, with no third-party packages, network calls or model service. Save plain UTF-8 files. Commands use python; use your known interpreter command if it is named differently. Confirm the version rather than assuming which installation a terminal has selected.

mkdir tdd-lab
cd tdd-lab
python --version

Read a sample · Chapter 02 of 06

The red stage is useful evidence only when the intended test actually runs and rejects missing behaviour. A syntax error or an undiscovered test is a different problem.

Create fee.py with this intentionally incomplete implementation. It is a temporary starting point, not a usable answer. Returning zero makes a concrete false prediction that our first examples can reject. Keep it inside the practice directory so nobody mistakes it for a finished delivery rule.

def delivery_fee(subtotal_pence, express=False):
    return 0

Now create test_first.py exactly as shown. Each method names one observable condition and compares a literal expected fee with the public function result. The second case deliberately combines express delivery with the free standard threshold, so the distinction appears early. The file imports fee, which must be fee.py beside it, rather than an unrelated installed module.

import unittest
from fee import delivery_fee


class FirstExamples(unittest.TestCase):
    def test_standard_below_threshold(self):
        self.assertEqual(delivery_fee(4999), 499)

    def test_express_still_costs_above_threshold(self):
        self.assertEqual(delivery_fee(5000, express=True), 899)


if __name__ == '__main__':
    unittest.main()

python -m unittest -v test_first

Expected red result for the temporary implementation:
Ran 2 tests
FAILED (failures=2)

The recorded run produced two assertion failures: zero was returned where 499 and 899 were required. Your timings and file paths may differ. Read the assertion lines as well as the summary. An import failure means the example never reached delivery_fee; fix the filename, directory or interpreter problem first. A message saying zero tests ran is not evidence that the fee logic works.

Keep this red result as a short note or local log. Do not write a unit test that expects a whole runner transcript, since paths, line numbers and timings change. The useful evidence is the command, two discovered tests, the mismatched outputs and the reason those outputs contradict the contract.

The red, green, refactor cycle works in small increments. You establish one missing behaviour, implement enough to satisfy it, and improve structure while retaining that behaviour. This workbook starts with two closely related examples to make the competing delivery rules visible; it is not a rule that every change must begin with exactly two tests.

Read a sample · Chapter 03 of 06

An assistant can propose code, but the contract and tests remain the decision boundary. Give it the smallest relevant context and request a reviewable change.

The following is a reusable prompt, not a transcript of an external assistant conversation. Paste your contract, the two files and the actual failing output when using it. Use a practice workspace without credentials or private customer material. You can also complete the lab manually; an AI account is not required for the printed exercise.

Implement delivery_fee in fee.py using the attached contract.
The attached tests fail against the intentional return-zero stub.
Change only fee.py. Keep its public name and arguments.
Do not edit, delete, skip or weaken the tests.
Use Python built-ins only; no network calls or file writes.
Reject invalid types and ranges explicitly.
Return a small diff and explain each branch.
Distinguish tests you actually ran from commands you suggest.

Before applying a response, inspect both its scope and behaviour. A proposal that changes tests to expect zero has removed the evidence rather than fixed the function. A proposal that downloads a package or reads unrelated files is outside this small task. Ask for a narrower diff or make the correction yourself. The assistant does not acquire permission to expand the job from its own generated instructions.

Here is the worked implementation for fee.py. The validation makes invalid input explicit before the fee rules run. Python Boolean values are a subtype of integers, so this contract uses exact type comparison to reject them as money. That strict choice also excludes custom integer subclasses; it is a policy for this exercise rather than a universal preference.

FREE_THRESHOLD_PENCE = 5_000
STANDARD_FEE_PENCE = 499
EXPRESS_FEE_PENCE = 899
MAX_SUBTOTAL_PENCE = 1_000_000


def delivery_fee(subtotal_pence, express=False):
    if type(subtotal_pence) is not int:
        raise TypeError('subtotal_pence must be an integer, not bool')
    if not 0 <= subtotal_pence <= MAX_SUBTOTAL_PENCE:
        raise ValueError('subtotal_pence is outside the supported range')
    if type(express) is not bool:
        raise TypeError('express must be a bool')
    if express:
        return EXPRESS_FEE_PENCE
    if subtotal_pence >= FREE_THRESHOLD_PENCE:
        return 0
    return STANDARD_FEE_PENCE

Express is checked before the standard free threshold because those rules overlap. The constants name the units and meanings of the values. They do not make a policy configurable at runtime, nor do they supply currency conversion or tax logic. Keeping a pure function makes the result depend only on the provided arguments.

python -m unittest -v test_first

Expected after replacing fee.py:
Ran 2 tests
OK

Run the command yourself after saving the proposed file. A statement that tests pass is not the same as observed output from this checkout. These two examples now pass in the recorded run, but they leave many valid and invalid inputs unexamined. Green means the selected assertions passed, not that every requirement has been demonstrated.

Read a sample · Chapter 04 of 06

A small green suite is a starting point. Add cases that separate plausible mistakes from the intended rule, especially at thresholds and input-type boundaries.

Create test_fee.py beside the other files. Its expected fees come from the contract. It does not import the implementation constants to calculate expected results: changing a fee constant should make a fixed policy test fail until the policy change is reviewed. Parameterised subtests label failing inputs without making separate test methods for every row.

import unittest
from fee import delivery_fee


class DeliveryFeeTests(unittest.TestCase):
    def test_standard_boundary_examples(self):
        for subtotal, expected in [(0, 499), (4999, 499),
                                   (5000, 0), (1_000_000, 0)]:
            with self.subTest(subtotal=subtotal):
                self.assertEqual(delivery_fee(subtotal), expected)

    def test_express_is_always_paid(self):
        for subtotal in [0, 4999, 5000, 1_000_000]:
            with self.subTest(subtotal=subtotal):
                self.assertEqual(delivery_fee(subtotal, True), 899)

    def test_subtotal_rejects_other_types(self):
        for value in [True, False, None, '5000', 5000.0]:
            with self.subTest(value=value):
                with self.assertRaises(TypeError):
                    delivery_fee(value)

    def test_subtotal_rejects_outside_range(self):
        for value in [-1, 1_000_001]:
            with self.subTest(value=value):
                with self.assertRaises(ValueError):
                    delivery_fee(value)

    def test_express_requires_boolean(self):
        for value in [None, 0, 1, 'yes', []]:
            with self.subTest(value=value):
                with self.assertRaises(TypeError):
                    delivery_fee(5000, value)

    def test_omitted_express_means_standard(self):
        self.assertEqual(delivery_fee(2500),
                         delivery_fee(2500, False))

    def test_result_is_integer_pence(self):
        for value, express in [(0, False), (5000, False),
                               (5000, True)]:
            self.assertIs(type(delivery_fee(value, express)), int)

    def test_calls_do_not_change_later_results(self):
        self.assertEqual(delivery_fee(5000, True), 899)
        self.assertEqual(delivery_fee(0), 499)
        self.assertEqual(delivery_fee(5000), 0)
        self.assertEqual(delivery_fee(5000, True), 899)


if __name__ == '__main__':
    unittest.main()

python -m unittest -v test_first test_fee

Expected combined result:
Ran 10 tests
OK

There are two first-example methods and eight expanded methods. Subtests cover more input cases than that runner count suggests. Read counts accurately when reporting results. The recorded release additionally checked 106 selected subtotals around the threshold and limits, making 318 direct calls across standard, explicit False and express modes. Those checks supplement the printed ten-test suite; they are not a benchmark or proof over every possible Python object.

The type and range tests express separate contract decisions. TypeError is required for a string subtotal, and ValueError for an integer just outside the permitted range. Testing only that some exception occurs could accept a NameError caused by a typo. The suite does not lock down exception message wording because wording is not part of this contract.

The repeat-call case checks that an express calculation does not contaminate a later standard result. This is a useful guard against accidental mutable state, not a concurrency test. Likewise, checking an integer return type catches a float result even if 499.0 compares numerically equal to 499. Each assertion should have a failure you can explain.

Read a sample · Chapter 05 of 06

Passing tests become more informative when you know they reject realistic defects. Deliberately alter one rule in an isolated copy, observe the failure, then restore the correct version.

A mutation is a deliberate small code defect used to probe the tests. Make it in a separate practice copy, and never distribute that copy as the working solution. Run the suite, identify the expected failure and restore the correct code before proceeding. If a mutation does not fail, investigate whether the tests miss the behaviour or whether the edit changed nothing observable under this contract.

Scroll sideways to see every column.

All three defects above were made separately against the printed implementation and rejected by the expanded learner suite. This establishes sensitivity to these three changes. It does not give an overall mutation score or establish that the tests detect every meaningful defect. A surviving mutant can sometimes be equivalent for the supported inputs; classify it before adding an assertion merely to increase a number.

Refactoring changes organisation while preserving supported behaviour. For a small exercise, rename a private constant consistently or extract a validation helper without changing the public function name, arguments, results or exceptions. Run the unchanged suite immediately. Avoid combining a refactor with a new discount rule: if behaviour changes intentionally, write and review that new contract separately.

When the lab is in an existing practice Git repository, inspect its status and diff before accepting a patch. Keep tests visible alongside source. If the files are new and untracked, an ordinary diff does not show their contents; open them directly as well. The staged diff shows what is prepared for the next commit, which may differ from the current working files.

git status --short
git diff -- fee.py test_first.py test_fee.py
git diff --cached -- fee.py test_first.py test_fee.py

Ask an assistant to explain a failing mutation or suggest a smaller refactor, then compare that suggestion with the actual diff. Do not approve a change solely because its explanation sounds convincing. Inspect removed assertions, skipped tests, broad exception handlers and added side effects. Retain useful test failures in your notes instead of repeatedly regenerating both code and tests until the output becomes green.

Read a sample · Chapter 06 of 06

A useful handover connects the request, changed files and observed checks. It also states which behaviours remain outside the evidence, so the next person knows what to verify.

The finished lab contains fee.py, test_first.py and test_fee.py. Its policy is fictional, with no network or persistent state. Record the interpreter version, exact test command, discovered method count and result. Include a short description of each deliberately caught defect. Separate a check you ran from a suggested future check, and record any assistant contribution as a proposal reviewed against the contract.

Change: implement fictional delivery_fee contract.
Files: fee.py, test_first.py, test_fee.py.
Run: python -m unittest -v test_first test_fee
Recorded environment: Python 3.12.10, Windows 11.
Result: 10 test methods passed.
Probe: three named defects were each rejected in isolation.
Scope: pure local fee calculation, integer pence only.
Not checked: checkout integration, concurrency, public service.

A unit test of delivery_fee does not establish that a website passes the correct subtotal or handles its exceptions well. A real caller might use pounds instead of pence, pass a string from a form or forget the express choice. An integration test should exercise that boundary with representative input and check both displayed results and error handling. Do not add a database or browser to this lab merely to make the test suite look larger.

If a real feature requires currencies, discounts, postcode eligibility, refunds or policy changes, revisit the specification first. Decide the source of each rule and test its interactions. Avoid turning this fictional tariff into business advice. The lesson is how to establish and preserve a small contract, not which delivery prices to charge.

AI assistance can reduce typing and suggest overlooked cases, but speed is not evidence of correctness. Ask for one bounded patch at a time, inspect the changed files, rerun the acceptance checks and keep an explanation of decisions that matter. Where expected outcomes are unclear, investigate the requirement rather than asking a model to invent certainty. You remain responsible for choosing the oracle and accepting the result.

The next step is to use the same approach on a small feature in an app you already understand. Select a pure function or narrow boundary first. Write a failing example before implementation, add the edge cases that matter, and finish with a reviewable diff and clear evidence. Broader application evaluation complements these checks when outcomes depend on models, external tools or changing data.