thkt/use-workflow-tdd-cycle

TDD Cycle

Test behavior via public API. Mock only at system boundaries.

Variant Selection

| Trigger | Variant | Reference | | --------------------------------- | --------------- | ------------------------------------------------ | | spec.md / new feature (/code) | Feature-driven | ${CLAUDE_SKILL_DIR}/references/feature-driven.md | | Bug report / regression (/fix) | Bug-driven | ${CLAUDE_SKILL_DIR}/references/bug-driven.md | | Coverage gap in existing codebase | Coverage-driven | Active tests, no skip. Reuse RGRC below |

What to Test

| Priority | What | | ---------- | ---------------------------------------------------- | | Must | Business logic, services, critical paths, edge cases | | Contextual | Complex utils, custom hooks, transformations | | Skip | Simple accessors, UI layout, external lib behavior |

When NOT to Use TDD

| Context | Reason | | ------------------------ | --------------------------------- | | Prototypes (throwaway) | Discard likely, cost > benefit | | External API integration | Mock the API, not the integration | | Simple one-off scripts | Shorter than the test would be | | UI experiments | Visual first, extract logic later |

Feature-Driven vs Bug-Driven

| Aspect | Feature-Driven | Bug-Driven | | ---------- | --------------------------- | --------------------- | | Trigger | Specification | Bug report | | Test state | Skip state initially | Active | | Test count | All tests generated upfront | 1 main + edge cases | | Activation | User-controlled | Immediate | | Focus | Feature completion | Regression prevention |

Test Philosophy (Classical/Detroit)

| Principle | Rule | | ---------------------------- | --------------------------------------------------------- | | Behavior over implementation | Test public API output, not internal calls | | State verification | Assert on result values, not "was X called" | | Real objects first | Use real dependencies. Mock only external I/O | | Black-box perspective | Treat the unit as a black box via its public interface | | Sociable tests | Let collaborators participate. Isolate only at boundaries |

RGRC Cycle

| Phase | Goal | Rule | Common Mistake | | -------- | ------------ | -------------------------------------------------------------------------- | ------------------------------ | | Red | Failing test | Verify failure matches the intended behavior gap, not syntax/import errors | Test passes immediately | | Green | Pass test | "You can sin" - dirty OK | Over-implementing | | Refactor | Refine | Keep tests green. Shrink only while it reads easier (rules/PRINCIPLES.md) | Changing behavior; compressing | | Commit | Save state | All checks pass | Skipping checks |

Baby Steps (2-min cycle)

30s: Write failing test → 1min: Make pass → 10s: Run tests → 30s: Tiny refactor → 20s: Commit if green. Bugs are always in the last 2-minute change.

Vertical Slices Only

Stack RGRC cycles vertically per behavior. Never expand horizontally by writing all tests first and all implementations later.

Wrong (horizontal):
  Red:   test1, test2, test3, test4, test5
  Green: impl1, impl2, impl3, impl4, impl5

Right (vertical):
  Red → Green: test1 → impl1
  Red → Green: test2 → impl2
  ...

| # | Hazard from horizontal slices | | - | ---------------------------------------------------------------------------- | | 1 | Bulk-written tests verify imagined behavior instead of real behavior | | 2 | Tests degrade into structural assertions (data shape, signature) only | | 3 | Sensitivity to behavior change drops (pass when broken, fail when correct) | | 4 | Implementation knowledge follows test structure instead of guiding it |

Reference: mattpocock/skills tdd SKILL.md.

Test Failure Judgment

When a test fails, decide whether to fix the test or the implementation.

| Judgment | Condition | Action | | -------- | ------------------------- | ------------------------------------ | | Impl bug | Test matches spec/FR-xxx | Fix implementation. Don't touch test | | Test bug | Test diverges from spec | Fix test | | Unclear | Spec ambiguous or missing | Escalate to user |

For bug-driven flows (/fix), reproduction steps serve as the spec.

Test Design

| Technique | Use For | Example | | ------------------------ | --------------------- | ---------------------- | | Equivalence Partitioning | Group same behavior | Age: <18, 18-120 | | Boundary Value | Test edges | 17, 18, 120, 121 | | Decision Table | Multi-condition logic | isLoggedIn × isPremium |

Assertion Quality

Every test must verify a specific outcome. Weak assertions alone are forbidden.

| Category | Matchers | When acceptable | | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------- | | Weak (existence) | toBeTruthy, toBeDefined, toBeFalsy, toBeNull, toBeUndefined | Only with a meaningful assertion in the same test | | Meaningful (value) | toBe, toEqual, toStrictEqual, toMatch, toContain, toThrow, toHaveLength | Always preferred | | Meaningful (call) | toHaveBeenCalledWith, toHaveBeenCalledTimes, toHaveReturnedWith | When verifying side effects |

Bad: expect(result).toBeTruthy() Good: expect(result).toEqual({ id: 1, name: "Alice" })

One test, one concept. If two tests assert the same function with the same argument pattern, merge or parameterize with test.each.

Mock

Mock at system boundaries: external APIs, databases, file system, network, non-deterministic dependencies (time, random), slow dependencies that block the 2-min cycle.

| Rule | Threshold | | ------------------- | -------------------------------- | | Mock count per test | Must not exceed assertion count | | Mock scope | External dependencies only | | Mock target | Never mock the module under test |

| Anti-Pattern | Problem | Instead | | --------------------------- | ------------------------------------------- | ------------------------------------------ | | Assert mock was called | Tests mock behavior, not component behavior | Assert on observable output or side effect | | Test-only production method | Pollutes production API for test access | Extract to test utility or use public API | | Mock before understanding | Hides real dependency behavior | Understand dependency first, then mock | | Partial mock structure | Missing fields cause false passes | Mirror complete real API structure | | Mock overuse | More mocks than assertions = testing wiring | Reduce mocks or add meaningful assertions |

UT Isolation

Unit tests import only: target module + types + test infrastructure. Build test data from types or literals.

Test Construction

AAA Pattern

test("name", () => {
  // Arrange - Setup
  // Act - Execute
  // Assert - Verify
});

Naming

| Level | Pattern | | ----- | ------------------------------------------------ | | Suite | describe("[Target]", ...) | | Group | describe("[Method]", ...) | | Test | it("when [condition], should [expected]", ...) |

Framework Detection

| Condition | Framework | | ------------------ | --------- | | vitest in deps | Vitest | | jest in deps | Jest | | bun as runtime | Bun test | | No framework found | Vitest |

References

| Topic | File | | -------------- | --------------------------------------------------------- | | Feature-driven | ${CLAUDE_SKILL_DIR}/references/feature-driven.md | | Bug-driven | ${CLAUDE_SKILL_DIR}/references/bug-driven.md | | Flaky tests | ${CLAUDE_SKILL_DIR}/references/flaky-test-management.md | | Coverage | ${CLAUDE_SKILL_DIR}/../../rules/development/THRESHOLDS.md |