Test First by Evidence

• This is

  debugging-by-evidence

  pointed forward. One says no hypothesis before a command that reproduces. This one says no implementation before a test that failed.
• The weight sits in Watch it fail. Everything else is what to do once the red is real.
• You opened this in the middle of something. This is how to do that work, not a replacement for it. Name what you were doing before you start, and return to it when this is done.

The law

NO PRODUCTION CODE WITHOUT A TEST YOU WATCHED FAIL

• Code written before its test is unproven, and gets re-derived from a red rather than wrapped in a test that passes immediately.
• Make it recoverable before removing anything. Discarding work the human has not agreed to discard is not yours to do.
• A test that passes the first time you run it is not a test yet. It describes what the code already does.
• A test that errors is not a red. An error is a broken test; a failure is a working test with nothing to satisfy it.

Establish before the first test

• Never ask what the repository answers. Three things settle the setup, and it holds all three.
  • The command this project already uses to run tests.
  • Where its tests live, and what a neighbouring test looks like.
  • The runner, so the failure output means something to you.
• Read one nearby test before writing yours. Style is local, and a test that fights the local style is a second convention.

Which rules to read

• One rule per row. Enter at the matched row, then follow the cycle in order.
• A small change reads two rows. A new subsystem reads most of them. That difference is the point.
• Where two rows match, read both. Under-reading costs a wrong test. Over-reading costs one file.

rules/watch-it-fail.md

rules/smallest-green.md

rules/where-the-test-goes.md

rules/tests-that-cannot-lie.md

rules/code-written-first.md

rules/bug-fix-starts-red.md

rules/hard-to-test-is-a-signal.md

• Watch it fail against code written first. The first owns the normal path. The second owns the recovery when the order was already broken.
• Where it goes against what makes it honest. Placement decides which seam. Honesty decides what it asserts once it is there.
• Bug fix against watch it fail. A bug fix starts from a red that reproduces a defect. The general case starts from a red that describes a wish.

• Write the test, run it, and watch it fail before writing any implementation.
• Then write the least code that passes, and run the whole suite.
• Never claim a phase you have not observed. A predicted failure is not a red.

Say which phase you are in

NO-TEST

RED

GREEN

REFACTORED

• Skipping a phase is the failure this skill exists to prevent.

• RED

  requires a run you performed. Not a prediction that it would fail.

• GREEN

  includes the rest of the suite. One new green and three new reds is not green.

Do not skip this when

• The change is one line. A one-line change to the wrong line is still wrong.
• The code is too simple to break. Simple code breaks. The test costs thirty seconds.
• You already tested it by hand. Manual testing leaves no record and does not re-run.
• You will add tests after. Tests written after pass immediately, which proves nothing about whether they can catch anything.
• You are only exploring. Fine. Throw the exploration away and start again with a test.

Routing

• The table above selects the rule. Read a selected rule in full, and say which one you opened, in one line.
• Judging tests inside a change under review belongs to a review of the diff, not here.
• Choosing a framework is a project decision, not this skill's.
• A direct instruction from the user outranks anything here.