Test-Driven Development (TDD) Workflow

Development Mode Configuration (CRITICAL)

[NOTE] This workflow is selected based on .moai/config/sections/quality.yaml :

constitution: development_mode: tdd # or ddd

When to use this workflow:

• development_mode: tdd → Use TDD (this workflow, default)

• development_mode: ddd → Use DDD instead (moai-workflow-ddd)

Key distinction:

• TDD (default): Test-first development for all work, including brownfield projects with pre-RED analysis

• DDD: Characterization-test-first for existing codebases with minimal test coverage

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