Tests exist to catch regressions and document intent. Coverage numbers are a side effect, not a goal.

When to use

"Write tests for this function/class/module"
"Add tests for the new feature"
"Improve test coverage in X"
"This isn't tested — fix that"

Procedure

1. Detect the stack

Find the existing test framework and conventions before writing anything new:

# Quick stack sniff
ls package.json composer.json pyproject.toml Cargo.toml go.mod 2>/dev/null
grep -l 'vitest\|jest\|pytest\|phpunit\|pest\|mocha\|rspec' \
  package.json composer.json pyproject.toml 2>/dev/null

Then read one existing test file to match style: file location, naming (*.test.ts vs *_test.go vs test_*.py), helpers, factories.

Always match existing conventions. A "better" test style in an inconsistent codebase is a worse test.

2. Decide what to test

For each unit under test, ask:

Category	Examples
Happy path	Typical input → expected output
Edge cases	Empty, null, zero, one, max, boundary, off-by-one
Error paths	Bad input, missing dependency, network/IO failure
Branches	Every meaningful `if` / `switch` / `match` arm
Invariants	Things that must always be true (idempotency, sort order, …)

Don't test:

Trivial getters/setters
Third-party library internals
Generated code
Implementation details (private methods, internal call order)

3. Structure each test: Arrange / Act / Assert

def test_user_can_redeem_valid_coupon():
    # Arrange — set up the world
    user = make_user()
    coupon = make_coupon(code="SAVE10", percent=10)

    # Act — do the one thing
    result = redeem(user, coupon)

    # Assert — check the outcome
    assert result.discount == 10
    assert coupon.used_by == user.id

One Act per test. If you have two, it's two tests.

4. Name tests for behavior, not implementation

Test names are sentences the codebase tells you when something breaks.

✅ redeem_marks_coupon_as_used_for_redeeming_user
✅ it returns 404 when product does not exist
❌ test_redeem_1
❌ testRedeemFunction

5. Assert on observable behavior

Tests should fail when the behavior changes, not when the code structure changes.

✅ "After register(), the user can log in with that email"
❌ "After register(), userRepository.save was called once with {email: ...}"

The second one breaks the moment you rename a repo, even though behavior is unchanged.

6. Run and iterate

Run the new test → it must pass
Break the code under test deliberately → the test must fail (otherwise it doesn't actually test anything)
Run the full suite → must still pass

Common pitfalls

Pitfall	Why it hurts	Fix
Testing mocks instead of behavior	Refactors break tests even when behavior is preserved	Assert on outputs/state, not on mock calls
Shared mutable fixtures	Tests pass/fail depending on order	Fresh setup per test, or explicit factories
Time-dependent tests	Flaky on slow CI / different timezones	Inject a clock, freeze time
Hitting the network / real DB	Slow + flaky	In-memory DB, recorded fixtures, contract tests
Asserting too much	Brittle to unrelated changes	Assert only what the test name claims
Asserting too little	Test passes even when broken	Mutation test: break the code, watch the test fail
Sleep/setTimeout in tests	Flaky	Poll with timeout, or use the framework's async primitives

Output format

Report:

## Tests added: <scope>

**Framework:** <pytest / vitest / phpunit / …>

**Coverage:**
- ✅ Happy path: …
- ✅ Edge cases: …
- ✅ Error paths: …

**Deliberately not covered (and why):**
- …

**How to run:**
\`\`\`
<exact command>
\`\`\`

Anti-patterns

❌ Writing tests after deploying — you tested in prod, then doubled down
❌ Chasing 100% coverage by testing trivia
❌ One giant test that does seven things
❌ Tests that pass without an assertion (yes, this happens)
❌ Skipped/commented-out tests left in the codebase

¶When to use

¶Procedure

¶1. Detect the stack

¶2. Decide what to test

¶3. Structure each test: Arrange / Act / Assert

¶4. Name tests for behavior, not implementation

¶5. Assert on observable behavior

¶6. Run and iterate

¶Common pitfalls

¶Output format

¶Anti-patterns