TDD

TDD Reminder

General Guidelines

Output Style

• Never explicitly mention TDD in code, comments, commits, PRs, or issues
• Write natural, descriptive code without meta-commentary about the development process
• The code should speak for itself - TDD is the process, not the product

Beads is available for task tracking. Use mcp__beads__* tools to manage issues (the user interacts via bd commands).

Plan File Restriction

NEVER create, read, or update plan.md files. Claude Code's internal planning files are disabled for this project. Use other methods to track implementation progress (e.g., comments, todo lists, or external tools).

TDD Fundamentals

The TDD Cycle

The foundation of TDD is the Red-Green-Refactor cycle:

1. Red Phase: Write ONE failing test that describes desired behavior

   • The test must fail for the RIGHT reason (not syntax/import errors)
   • Only one test at a time - this is critical for TDD discipline
     • Exception: For browser-level tests or expensive setup (e.g., Storybook *.stories.tsx), group multiple assertions within a single test block to avoid redundant setup - but only when adding assertions to an existing interaction flow. If new user interactions are required, still create a new test. Split files by category if they exceed ~1000 lines.
   • Adding a single test to a test file is ALWAYS allowed - no prior test output needed
   • Starting TDD for a new feature is always valid, even if test output shows unrelated work
   • For DOM-based tests, use data-testid attributes to select elements rather than CSS classes, tag names, or text content
   • Avoid hard-coded timeouts both in form of sleep() or timeout: 5000 etc; use proper async patterns (waitFor, findBy*, event-based sync) instead and rely on global test configs for timeout settings

2. Green Phase: Write MINIMAL code to make the test pass

   • Implement only what's needed for the current failing test
   • No anticipatory coding or extra features
   • Address the specific failure message

3. Refactor Phase: Improve code structure while keeping tests green

   • Only allowed when relevant tests are passing
   • Requires proof that tests have been run and are green
   • Applies to BOTH implementation and test code
   • No refactoring with failing tests - fix them first

Core Violations

1. Multiple Test Addition

   • Adding more than one new test at once
   • Exception: Initial test file setup or extracting shared test utilities

2. Over-Implementation

   • Code that exceeds what's needed to pass the current failing test
   • Adding untested features, methods, or error handling
   • Implementing multiple methods when test only requires one

3. Premature Implementation

   • Adding implementation before a test exists and fails properly
   • Adding implementation without running the test first
   • Refactoring when tests haven't been run or are failing

Critical Principle: Incremental Development

Each step in TDD should address ONE specific issue:

• Test fails "not defined" → Create empty stub/class only
• Test fails "not a function" → Add method stub only
• Test fails with assertion → Implement minimal logic only