Strategy — Test-Driven Changes

When to use

• The task adds or changes behavior in a codebase that has a test suite, where a test can capture the expected outcome before the code is written.
• The task fixes a bug whose failure can be reproduced by a test that fails before the fix and passes after it.
• The user explicitly asks to work test-first, to write a failing test before the implementation, or to keep the suite green throughout.

When NOT to use

• Do not force a failing-test-first flow on a throwaway exploratory spike where no test infrastructure exists and the code will be discarded.
• Do not demand a new test for a change that alters no behavior — pure formatting, comments, or renaming a private symbol covered by existing tests.

Core guidance

• Keep the whole suite green after the change — Run the full relevant test suite after the change and ensure every test passes, not just the one you added.
• Make each test fail for exactly one reason — Keep each test focused so it can fail for exactly one reason, and name it after the behavior it verifies.
• Refactor only while the suite stays green — Once the test is green, refactor in small steps and re-run the suite after each, so the tests catch any behavior drift the cleanup introduces.
• Assert observable behavior, not internals — Assert the observable behavior and public contract of the code under test rather than its private internals or call sequence.
• Write the failing test before the implementation — Write or extend a test that expresses the desired behavior and run it to confirm it fails for the intended reason before writing the implementation.

Never

• Never delete, skip, or loosen an assertion in a test just to turn it green; fix the code under test instead, or escalate if the test's expectation is wrong.

Prefer

• Prefer writing or extending a test that fails for the right reason before implementing the change, so the test proves the behavior once the code lands.

Avoid

• Avoid landing a behavior change with no accompanying test, and avoid leaving the suite red after your change.

Escalate to user when

• Escalate to the user when a change would require altering an existing test's expectation, since that may mean intentionally changing behavior and needs confirmation.

Quick recipe

1. Write or extend a test that captures the desired behavior, then run it and confirm it fails for the intended reason. (verify: The new test runs and fails with a message that clearly reflects the missing behavior, not a setup error.)
2. Implement the smallest change that makes the new test pass, then run the full relevant suite and confirm every test is green before finishing. (verify: The new test passes and the whole suite is green, with no test skipped or weakened to get there.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Over-mocking couples tests to internals — Asserting on every internal call and mocking collaborators heavily ties the test to the current implementation rather than the behavior. Fix: Test through the public interface with real collaborators where practical, and mock only true external boundaries.
2. A test that was never seen to fail — Writing the test after the implementation and never watching it fail can hide a test that passes even when the behavior is broken. Fix: Temporarily break the implementation or write the test first and confirm it goes red for the intended reason before making it green.
3. Running only the new test, not the suite — Running only the one test you just wrote can leave a regression elsewhere undetected until much later. Fix: Run the full relevant suite before declaring the change done, and treat any red test as blocking.

Version notes

• Test-driven discipline is version-agnostic (PHP >=7.4) — Writing a failing test first and keeping the suite green is a strategy that applies to any PHP version; it constrains the order in which the agent works, not which language features it uses, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-test-driven.yaml.

Additional resources

• references/anti-patterns.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-minimal-diff, ai-rules/strategy-no-untested-refactor, testing/pest-basics