tdd

# Test-Driven Development

TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after.

When exploring the codebase, read `GLOSSARY.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.

## Discover the Stack First

The TDD cycle is universal; the commands are not. Before writing the first test, discover how *this* repository tests, and use its commands for every RED, GREEN, and verification step:

- **Language and build system** — `package.json`, `pom.xml`/`build.gradle`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, a `Makefile`

- **Checked-in wrappers** — prefer `./gradlew`, `./mvnw`, `make test`, or a repo script over globally installed tools

- **Test framework and configuration** — and how it runs a single focused test vs the full suite

- **Existing conventions** — where tests live, how files are named, what patterns neighboring tests follow

- **Documented commands** — README, CONTRIBUTING, and CI workflows show the commands that actually gate merges

Never assume a default like `npm test` — a Gradle, Cargo, or pytest project has its own equivalent.

## What a good test is

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it doesn't care about internal structure.

See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines. tests.md also holds the checks a test passes before it is kept: the break it names, the undefined check, assertions on the real component rather than its double, and the mutation check.

## Seams: where tests go

A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.

**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them: the change record's frame or plan section, a ticket's acceptance, or a standing testing grant that establishes the public boundary is that confirmation, and for a small settled change the accepted observable behavior and the existing public interface establish it. Ask the owner only when a consequential seam choice remains open, not for an ordinary test shape. No test is written at an unconfirmed seam. You can't test everything, so agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.

## Anti-patterns

- **Implementation-coupled**: mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.

- **Tautological**: the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, the spec.

- **Horizontal slicing**: writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead: one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.

## Rules of the loop

- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.

- **One slice at a time.** One seam, one test, one minimal implementation per cycle.

- **Refactoring is not part of the loop.** It belongs to the review step, not the red → green implementation cycle.

### Verify RED - Watch It Fail

**MANDATORY. Never skip.**

Confirm:

- Test fails (not errors)

- Failure message is expected

- Fails because feature missing (not typos)

**Test passes?** You're testing existing behavior. Fix test.

**Test errors?** Fix error, re-run until it fails correctly.

### Verify GREEN - Watch It Pass

**MANDATORY.**

Confirm:

- Test passes

- Other tests still pass

- Output pristine (no errors, warnings)

**Test fails?** Fix code, not test.

**Other tests fail?** Fix now.

# Good and Bad Tests

## Good Tests

**Integration-style**: Test through real interfaces, not mocks of internal parts.

```typescript

// GOOD: Tests observable behavior

test("user can checkout with valid cart", async () => {

const cart = createCart();

cart.add(product);

const result = await checkout(cart, paymentMethod);

expect(result.status).toBe("confirmed");

});

```

Characteristics:

- Tests behavior users/callers care about

- Uses public API only

- Survives internal refactors

- Describes WHAT, not HOW

- One logical assertion per test

### DAMP Over DRY in Tests

In production code, DRY (Don't Repeat Yourself) is usually right. In tests, **DAMP (Descriptive And Meaningful Phrases)** is better. A test should read like a specification — each test should tell a complete story without requiring the reader to trace through shared helpers.

Duplication in tests is acceptable when it makes each test independently understandable.

Before writing the test body, answer: **what production change should make this test fail — and is that change a bug or a decision?** A test earns its place by catching a wrong branch, missing side effect, wrong argument, boundary case, or broken contract.

**No change detectors.** If only intentional decisions can fail a test — a constant's value, exact message wording, private structure — it fires on redesign and sleeps through bugs. Test the behavior that depends on the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is retried 5 times and the 6th attempt never happens."

**Behavior, not text.** Asserting that a script, skill, or config contains an exact line proves only that the source is the source. Run scripts against controlled inputs and assert outputs, side effects, or exit codes.

**Your code, not the framework.** Test the contract your code makes at its boundaries — the route you register, the query you emit, the payload you produce. Upstream mechanics are their maintainers' tests to write (the classic: asserting your router invokes a registered handler — that is the framework's test, not yours). When upstream behavior genuinely surprised you, write one narrow characterization test naming the assumption. The same boundary applies inside your code: constructors, getters, constants, and trivial forwarding earn tests only when they validate, normalize, default, derive, enforce, or cause side effects — otherwise assert the first consumer-visible result that depends on them.

### Gate Function

```

BEFORE writing the test body:

Name the production change that would make this test fail.

Cannot name one → redesign around an observable behavior

"The source text changed" → run the artifact and assert its effects

Only intentional decisions → change detector; test the behavior

that depends on the decision

Confirm the expected value is derived without the code under test.

IF it reuses the code's logic or helpers:

Replace it with a literal or hand-checked fixture

```

## Bad Tests

**Implementation-detail tests**: Coupled to internal structure.

```typescript

// BAD: Tests implementation details

test("checkout calls paymentService.process", async () => {

const mockPayment = jest.mock(paymentService);

await checkout(cart, payment);

expect(mockPayment.process).toHaveBeenCalledWith(cart.total);

});

```

Red flags:

- Mocking internal collaborators

- Testing private methods

- Test breaks when refactoring without behavior change

- Test name describes HOW not WHAT

- Verifying through external means instead of interface

```typescript

// BAD: Bypasses interface to verify

test("createUser saves to database", async () => {

await createUser({ name: "Alice" });

const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);

expect(row).toBeDefined();

});

// GOOD: Verifies through interface

test("createUser makes user retrievable", async () => {

const user = await createUser({ name: "Alice" });

const retrieved = await getUser(user.id);

expect(retrieved.name).toBe("Alice");

});

```

**Tautological tests**: Expected value restates the implementation, so the test passes by construction.

```typescript

// BAD: Expected value is recomputed the way the code computes it

test("calculateTotal sums line items", () => {

const items = [{ price: 10 }, { price: 5 }];

const expected = items.reduce((sum, i) => sum + i.price, 0);

expect(calculateTotal(items)).toBe(expected);

});

// GOOD: Expected value is an independent, known literal

test("calculateTotal sums line items", () => {

expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);

});

```

A test calls the code the way its users do and asserts the result they observe against a literal expected value. A test that asserts which calls the code made where the contract does not fix them, or restates a constant the code contains, does neither.

The check: before you keep a test, ask whether it would still pass if every function it imports returned `undefined`. If yes, it observes no behavior and cannot fail for a defect. Rewrite the assertion.

**Four shapes that still pass when every imported function returns `undefined`:**

- **Weak or no assertion.** No `expect`, or only `toBeDefined`, `toBeTruthy`, `not.toThrow`, `toBeInstanceOf`, `toBeGreaterThan(0)`.

- **Mock or absence only.** Only `toHaveBeenCalled`, `not.toHaveBeenCalled`, `toBeUndefined`, `toEqual([])`, `toHaveLength(0)`, `not.toBe(wrongValue)`.

- **Constant pin.** The assertion restates a hand-maintained constant, config default, table row, or prompt string: `expect(LIMITS.maxTools).toBe(8)`, `expect(PROMPT).toContain("You are")`.

- **Fixture asserts fixture.** The assertion reads data the test built or a value computed in `beforeEach`, and the subject never runs inside the body.

**The fix:** call the subject inside the test body with one concrete input and assert the literal output or the observable effect, `expect(slugify("Hello, World!")).toBe("hello-world")`. For an absence, assert the presence on the other input in the same test. For a constant, test the mechanism that reads it with one input instead of restating the value. For a mock, assert the payload it received or the state after the call, not that it was called. When no such assertion exists, removing the test is sweep-tests' work, with its mutation proof.

**Keep** a test of a relation across a table's rows (a key present in two tables, a parent that exists), and a compile-time check in a `*.test-d.ts` file.

**The mock earns no assertions.** A mock assertion passes when the mock is present and fails when it is absent — it says nothing about the component. Assert the real component's behavior; if the mock is what you are checking, unmock it or delete the assertion.

**Mock at the right level.** Learn every side effect of the real method before replacing it; mock the slow or external operation and keep what the test depends on real. When unsure, run the test against the real implementation first and observe what actually needs to happen.

**Make doubles specific.** When arguments, call counts, or ordering are part of the contract, assert them — a fake that accepts anything verifies nothing. Give each branch (success, error, malformed) its own fixture or spy, so the wrong branch cannot satisfy the expectation.

**Mirror real data completely.** Mock the complete structure as it exists in reality — all documented fields — not just the ones your test reads. Partial mocks fail silently when downstream code reads an omitted field: the test passes while integration breaks.

**Production classes carry production methods only.** Cleanup that only tests need lives in test utilities, never as a `destroy()` on the production class. Ask: is this method called only from tests? Does this class own this resource's lifecycle? Wrong answers → test utility.

**Prefer real components over complex mocks.** When mock setup outgrows the test logic, mocks miss methods the real components have, or tests break when the mock changes, switch to an integration test with real components.

## The Mutation Check

Before finishing, mentally mutate the production code; at least one test should fail for each realistic mutation:

- Wrong constant or argument

- Wrong branch handler

- Missing state change or side effect

- Empty or default return

- Missing validation for zero, empty, nil, unauthorized, or malformed input

A mutation nothing catches marks the behavior as unprotected — or the test as tautological.

# When to Mock

Mock at **system boundaries** only:

- External APIs (payment, email, etc.)

- Databases (sometimes - prefer test DB)

- Time/randomness

- File system (sometimes)

Don't mock:

- Your own classes/modules

- Internal collaborators

- Anything you control

## Designing for Mockability

At system boundaries, design interfaces that are easy to mock:

**1. Use dependency injection**

Pass external dependencies in rather than creating them internally:

```typescript

// Easy to mock

function processPayment(order, paymentClient) {

return paymentClient.charge(order.total);

}

// Hard to mock

function processPayment(order) {

const client = new StripeClient(process.env.STRIPE_KEY);

return client.charge(order.total);

}

```

**2. Prefer SDK-style interfaces over generic fetchers**

Create specific functions for each external operation instead of one generic function with conditional logic:

```typescript

// GOOD: Each function is independently mockable

const api = {

getUser: (id) => fetch(`/users/${id}`),

getOrders: (userId) => fetch(`/users/${userId}/orders`),

createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),

};

// BAD: Mocking requires conditional logic inside the mock

const api = {

fetch: (endpoint, options) => fetch(endpoint, options),

};

```

The SDK approach means:

- Each mock returns one specific shape

- No conditional logic in test setup

- Easier to see which endpoints a test exercises

- Type safety per endpoint

When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.

Do not force a test when it would be impractical. If the available test would require broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip adding a new test and use the closest useful verification instead.

## If a Failing Test Is Impractical

Use the closest executable regression check instead: a targeted script, manual reproduction command, browser automation, snapshot comparison, log assertion, or focused integration check.

Prefer no new test over a bad test. A bad test is one that mostly tests mocks, encodes current implementation details, depends on timing or unrelated global state, needs expensive infrastructure for a small fix, or would be deleted immediately after proving the fix.

## Guardrails

- Do not change tests merely to match a wrong implementation.

- Do not weaken existing assertions unless the expected behavior has genuinely changed and the reason is clear.

- Keep the regression test focused on the bug. Avoid broad fixture churn or unrelated coverage expansion.

- If the bug is flaky, make the test deterministic where possible and document the signal being locked down.

- If the bug exposes a broader class of failures, first land the focused regression path, then consider additional sibling coverage.

Report the evidence, not just the outcome:

- Name the failing-before test or executable check and the failure it produced.

- Name the passing-after test run and any nearby validation performed.

- If failing-before evidence could not be demonstrated, state why and describe the closest regression check used instead.