Tests First for Friday’s Checkout Release
Your team needs a shipping-fee change ready for Friday’s checkout release. An assistant can produce the function quickly, but speed means little if it misunderstands when free shipping applies. Start with executable examples, then let the assistant help implement the smallest change that satisfies them. Follow this walkthrough in a Python project with pytest available.
1. Define the shipping rules before opening the assistant
Use a small task with observable results. The function shipping_fee takes a subtotal in integer cents and an express flag that defaults to false. The subtotal is the amount after discounts. Standard shipping costs 499 cents below a 5,000-cent subtotal and becomes free at that threshold. Express adds 1,200 cents to whichever standard fee applies. A negative subtotal raises ValueError.
Write these rules in your task notes. Integer cents keep rounding outside this exercise. Input parsing, tax calculation, and carrier requests belong elsewhere; keeping this boundary explicit gives the assistant less room to invent behavior.
2. Ask the assistant for a test matrix
Give the assistant the rules and this instruction: “Propose input and expected-output pairs for shipping_fee. Cover the threshold, express shipping, and invalid input. Do not write implementation code. Flag any ambiguity before choosing an expected result.”
Review its proposal against these cases:
- Subtotal 0, standard: 499.
- Subtotal 4,999, standard: 499.
- Subtotal 5,000, standard: 0.
- Subtotal 5,001, standard: 0.
- Subtotal 4,999, express: 1,699.
- Subtotal 5,000, express: 1,200.
- Subtotal negative 1: ValueError.
The two express cases establish that free standard shipping does not remove the express surcharge. Resolve disagreements here, while changing an example is still cheap.
3. Create tests and a deliberately unfinished function
Ask the assistant to create shipping.py with the signature shipping_fee(subtotal_cents: int, express: bool = False) and a body that raises NotImplementedError. Have it create test_shipping.py beside that file, importing the function from shipping.
Request a pytest parameterized test for the six valid examples and a separate test using pytest.raises(ValueError) for the negative subtotal. Tell it to assert returned values directly and avoid mocks: this function has no external dependencies.
Read every expected value yourself. An assistant that writes both expectations and implementation can repeat the same misunderstanding in both places.
4. Run pytest and inspect the first failures
Run python -m pytest -q test_shipping.py from the directory containing both files. The valid examples should fail because the stub raises NotImplementedError. The invalid-input test should fail because that exception is not ValueError.
If collection fails because pytest is missing or the import path is wrong, fix that setup issue and rerun. You need evidence that the tests reach the unfinished function. Ask the assistant to explain any unexpected failure before it changes application code.
5. Implement only the agreed shipping behavior
Now prompt: “Implement shipping_fee to satisfy the reviewed rules. Keep the tests unchanged. Use straightforward conditionals and integer arithmetic. Do not add dependencies or additional features.”
Run the same test command again. Inspect the patch even when everything passes: negative subtotals should be rejected first, the threshold should include exactly 5,000 cents, and the express surcharge should apply on both sides of that threshold. Run the project’s existing suite too, if you are integrating this into an established repository.
6. Challenge the threshold test before refactoring
Temporarily change the implementation so free shipping starts above 5,000 cents. Rerun the tests. The exact-threshold examples should fail. Restore the correct comparison immediately and confirm the suite passes.
This deliberate mistake checks whether the tests detect a plausible regression. Then ask the assistant to review naming and duplication. Accept a refactor only when it improves readability, and rerun the tests afterward.
7. Save the rules with the assistant session
Keep the approved examples and test command in your repository’s contributor notes so the next assistant session starts from the same contract. For developers using Claude Code, Codex, or Gemini CLI, I recommend RelayVano as a pay-as-you-go relay for model access within that workflow. Sign up for RelayVano when you are ready to connect your preferred tool.
Before committing, review the final diff for unrelated edits and record the test result. Your release now has explicit shipping examples, a checked implementation, and a repeatable command for the next change.