Test-Driven Development (TDD) Workflow
Development Mode Configuration (CRITICAL)
[NOTE] This workflow is selected based on .moai/config/sections/quality.yaml:
constitution:
development_mode: hybrid
hybrid_settings:
new_features: tdd
legacy_refactoring: ddd
When to use this workflow:
development_mode: tdd → Always use TDDdevelopment_mode: hybrid + new package/module → Use TDDdevelopment_mode: hybrid + refactoring existing code → Use DDD instead (moai-workflow-ddd)
Key distinction:
- New file/package (doesn't exist yet) → TDD (this workflow)
- Existing code (file already exists) → DDD (ANALYZE-PRESERVE-IMPROVE)
Quick Reference
Test-Driven Development provides a disciplined approach for creating new functionality where tests define the expected behavior before implementation.
Core Cycle - RED-GREEN-REFACTOR:
- RED: Write a failing test that defines desired behavior
- GREEN: Write minimal code to make the test pass
- REFACTOR: Improve code structure while keeping tests green
When to Use TDD:
- Creating new functionality from scratch
- Building isolated modules with no existing dependencies
- When behavior specification drives development
- New API endpoints with clear contracts
- New UI components with defined behavior
- Greenfield projects (rare - usually Hybrid is better)
When NOT to Use TDD:
- Refactoring existing code (use DDD instead)
- When behavior preservation is the primary goal
- Legacy codebase without test coverage (use DDD first)
- When modifying existing files (consider Hybrid mode)
Core Philosophy
TDD vs DDD Comparison
TDD Approach:
- Cycle: RED-GREEN-REFACTOR
- Goal: Create new functionality through tests
- Starting Point: No code exists
- Test Type: Specification tests that define expected behavior
- Outcome: New working code with test coverage
DDD Approach:
- Cycle: ANALYZE-PRESERVE-IMPROVE
- Goal: Improve structure without behavior change
- Starting Point: Existing code with defined behavior
- Test Type: Characterization tests that capture current behavior
- Outcome: Better structured code with identical behavior
Test-First Principle
The golden rule of TDD is that tests must be written before implementation code:
- Tests define the contract
- Tests document expected behavior
- Tests catch regressions immediately
- Implementation is driven by test requirements
Implementation Guide
Phase 1: RED - Write a Failing Test
The RED phase focuses on defining the desired behavior through a failing test.
Writing Effective Tests
Before writing any implementation code:
- Understand the requirement clearly
- Define the expected behavior in test form
- Write one test at a time
- Keep tests focused and specific
- Use descriptive test names that document behavior
Test Structure
Follow the Arrange-Act-Assert pattern:
- Arrange: Set up test data and dependencies
- Act: Execute the code under test
- Assert: Verify the expected outcome
Verification
The test must fail initially:
- Confirms the test actually tests something
- Ensures the test is not passing by accident
- Documents the gap between current and desired state
Phase 2: GREEN - Make the Test Pass
The GREEN phase focuses on writing minimal code to satisfy the test.
Minimal Implementation
Write only enough code to make the test pass:
- Do not over-engineer
- Do not add features not required by tests
- Focus on correctness, not perfection
- Hardcode values if necessary (refactor later)
Verification
Run the test to confirm it passes:
- All assertions must succeed
- No other tests should break
- Implementation satisfies the test requirements
Phase 3: REFACTOR - Improve the Code
The REFACTOR phase focuses on improving code quality while maintaining behavior.
Safe Refactoring
With passing tests as a safety net:
- Remove duplication
- Improve naming and readability
- Extract methods and classes
- Apply design patterns where appropriate
Continuous Verification
After each refactoring step:
- Run all tests
- If any test fails, revert immediately
- Commit when tests pass
TDD Workflow Execution
Standard TDD Session
When executing TDD through manager-tdd:
Step 1 - Understand Requirements:
- Read SPEC document for feature scope
- Identify test cases from acceptance criteria
- Plan test implementation order
Step 2 - RED Phase:
- Write first failing test
- Verify test fails for the right reason
- Document expected behavior
Step 3 - GREEN Phase:
- Write minimal implementation
- Run test to verify it passes
- Move to next test
Step 4 - REFACTOR Phase:
- Review code for improvements
- Apply refactoring with tests as safety net
- Commit clean code
Step 5 - Repeat:
- Continue RED-GREEN-REFACTOR cycle
- Until all requirements are implemented
- Until all acceptance criteria pass
TDD Loop Pattern
For features requiring multiple test cases:
- Identify all test cases upfront
- Prioritize by dependency and complexity
- Execute RED-GREEN-REFACTOR for each
- Maintain cumulative test suite
Quality Metrics
TDD Success Criteria
Test Coverage (Required):
- Minimum 80% coverage per commit
- 90% recommended for new code
- All public interfaces tested
Code Quality (Goals):
- All tests pass
- No test written after implementation
- Clear test names documenting behavior
- Minimal implementation satisfying tests
TDD-Specific TRUST Validation
Apply TRUST 5 framework with TDD focus:
- Testability: Test-first approach ensures testability
- Readability: Tests document expected behavior
- Understandability: Tests serve as living documentation
- Security: Security tests written before implementation
- Transparency: Test failures provide immediate feedback
Integration Points
With DDD Workflow
TDD and DDD are complementary:
- TDD for new code
- DDD for existing code refactoring
- Hybrid mode combines both approaches
With Testing Workflow
TDD integrates with testing workflow:
- Uses specification tests
- Integrates with coverage tools
- Supports mutation testing for test quality
With Quality Framework
TDD outputs feed into quality assessment:
- Coverage metrics tracked
- TRUST 5 validation for changes
- Quality gates enforce standards
Troubleshooting
Common Issues
Test is Too Complex:
- Break into smaller, focused tests
- Test one behavior at a time
- Use test fixtures for complex setup
Implementation Grows Too Fast:
- Resist urge to implement untested features
- Return to RED phase for new functionality
- Keep GREEN phase minimal
Refactoring Breaks Tests:
- Revert immediately
- Refactor in smaller steps
- Ensure tests verify behavior, not implementation
Recovery Procedures
When TDD discipline breaks down:
- Stop and assess current state
- Write characterization tests for existing code
- Resume TDD for remaining features
- Consider switching to Hybrid mode
Version: 1.0.0
Status: Active
Last Updated: 2026-02-03
