Test first - red for the right reason, then green, then clean
A test written after the code passes by construction: it was shaped around what the code does, not
what it should do. Written first and seen failing, it proves what no later test can - that it can
fail, and that it fails for the behavior it names.
When to use
- Fires the moment before the first edit to a source file, in any language and test framework, whether or not the user said 'TDD' or 'tests'.
- The test-driven cycle, and the honest 'test: none' line, with its reason, when no test fits.
- Not for a config-only or docs-only edit or a throwaway spike, which record 'test: none' with the reason and go straight to the done gate.
The cycle
- Write the test. One behavior per test, named for that behavior, asserting the observable
result the requirement or the task card's acceptance names - never the implementation's
internals. Use the project's own framework, folder and naming. Code that talks to a database or an
external service also gets an integration test of that boundary.
- Watch it fail for the expected reason. Run it and read the failure. It counts as red only
when it compiled, RAN and failed on the assertion the behavior names - a compile error, a missing
fixture, an import typo or a skipped test is not red: fix that and run again. A test that passes
before the code exists tests nothing: fix the test, never the expectation. Quote the failing
assertion line in the reply or the seat report -
red: <test> - <assertion line>.
- Write the minimal code that passes. Only what the test demands - no option, branch or
abstraction a test does not ask for yet.
- See it green. Run it again with its neighbours (the file, or the project's scoped test
command) and read the result: the new test and every old one pass.
- Refactor while green. Tidy names, duplication and structure, re-running after each step. A
refactor that turns anything red is undone, not patched.
Then the next behavior, from step 1.
A bug fix
The test reproduces the bug first: it fails for the cause found (habits-root-cause, its 'Fix at the root, test first' step), then
the fix turns it green. A fix with no failing test first is a guess the suite cannot hold.
When no test fits
Config-only, docs-only, a throwaway spike, or code the project has no harness for: say so in one
line with the reason (test: none - <reason>), never skip it silently. A spike that becomes the
real code starts over at step 1.
Signs it was skipped
- Production code written before any test for it exists.
- A new test whose first run was green.
- A 'red' claimed over a run that never compiled or ran - 'Test suite failed to run', a compiler
error, zero tests executed - instead of the assertion line step 2 quotes.
- A test edited until it passes, instead of the code.
- 'Tested manually' standing in for a test the harness could run.
1---2name: habits-test-first3description: "Use before writing production code for a feature, bug fix or behavior change - before the first source edit. Not for config or docs edits, which skip tests."4user-invocable: false5metadata:6 source: https://skillmd.com/skills/envoydev/habits-test-first7---89# Test first - red for the right reason, then green, then clean1011A test written after the code passes by construction: it was shaped around what the code does, not12what it should do. Written first and seen failing, it proves what no later test can - that it can13fail, and that it fails for the behavior it names.1415## When to use1617- Fires the moment before the first edit to a source file, in any language and test framework, whether or not the user said 'TDD' or 'tests'.18- The test-driven cycle, and the honest 'test: none' line, with its reason, when no test fits.19- Not for a config-only or docs-only edit or a throwaway spike, which record 'test: none' with the reason and go straight to the done gate.2021## The cycle22231. **Write the test.** One behavior per test, named for that behavior, asserting the observable24 result the requirement or the task card's acceptance names - never the implementation's25 internals. Use the project's own framework, folder and naming. Code that talks to a database or an26 external service also gets an integration test of that boundary.272. **Watch it fail for the expected reason.** Run it and read the failure. It counts as red only28 when it compiled, RAN and failed on the assertion the behavior names - a compile error, a missing29 fixture, an import typo or a skipped test is not red: fix that and run again. A test that passes30 before the code exists tests nothing: fix the test, never the expectation. Quote the failing31 assertion line in the reply or the seat report - `red: <test> - <assertion line>`.323. **Write the minimal code that passes.** Only what the test demands - no option, branch or33 abstraction a test does not ask for yet.344. **See it green.** Run it again with its neighbours (the file, or the project's scoped test35 command) and read the result: the new test and every old one pass.365. **Refactor while green.** Tidy names, duplication and structure, re-running after each step. A37 refactor that turns anything red is undone, not patched.3839Then the next behavior, from step 1.4041## A bug fix4243The test reproduces the bug first: it fails for the cause found (`habits-root-cause`, its 'Fix at the root, test first' step), then44the fix turns it green. A fix with no failing test first is a guess the suite cannot hold.4546## When no test fits4748Config-only, docs-only, a throwaway spike, or code the project has no harness for: say so in one49line with the reason (`test: none - <reason>`), never skip it silently. A spike that becomes the50real code starts over at step 1.5152## Signs it was skipped5354- Production code written before any test for it exists.55- A new test whose first run was green.56- A 'red' claimed over a run that never compiled or ran - 'Test suite failed to run', a compiler57 error, zero tests executed - instead of the assertion line step 2 quotes.58- A test edited until it passes, instead of the code.59- 'Tested manually' standing in for a test the harness could run.