moai-workflow-tdd

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-develop:

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

Common Rationalizations

DAMP over DRY: In test code, prefer Descriptive And Meaningful Phrases over Don't Repeat Yourself. Duplication inside a test that makes the intent obvious is better than an abstraction that hides it.

Beyonce Rule: If you liked it, you should have put a test on it. Any behavior CI does not verify will eventually break without warning.

Red Flags

• Implementation file created in the same commit as its test file (RED phase skipped)
• Test names describe implementation (test_function_returns_true) instead of behavior (test_user_login_rejects_expired_token)
• All tests in a new file pass on first run — no RED phase was captured
• Commit message says "add tests" after the feature is already merged
• Test suite contains mocks of the code under test (mocking implementation, not collaborators)
• Coverage dropped in the commit that added a new feature

Verification

• Git history shows a failing-test commit before the implementation commit, or evidence of RED in the same commit
• Test names read as behavior specifications, not function descriptions
• Every new public function has at least one corresponding test case
• Full test suite passes (paste command output)
• Coverage for changed files is measured and reported (show tool output)
• No skip, xit, or disabled tests were added in this change
• REFACTOR phase was executed or explicitly justified as unnecessary

Test-First Anti-Cheat

[ZONE:Evolvable] [HARD] The Red Flags and Verification checklists above sit in advisory (evolvable) blocks and are consumed by no completion gate. This section promotes them into two enforced invariants that make test-first falsifiable in the completion matrix.

• Invariant i — RED failure output is mandatory completion evidence. The verbatim RED failing-test output (the failing-test run captured BEFORE any implementation makes it pass) MUST be observed and shown as part of run-phase completion evidence. A run that cannot produce this output skipped RED and cannot be reported as clean.
• Invariant ii — implementation written before its failing test is deleted and re-derived test-first. Any implementation code written before its failing test exists MUST be deleted and re-derived from a failing test (RED then GREEN). "I already wrote the implementation, so the test passes on first run" is the exact failure mode this invariant forbids — it is test-after, not test-first, and it leaves no RED output (Invariant i) to show as evidence.

These two invariants close the falsifiability gap: before them, a fully-passing self-verification matrix was producible with NO RED evidence, so test-first could not be distinguished from test-after by the completion report. After them, the matrix requires the verbatim pre-GREEN RED output, so a run that skipped RED has no such output to supply and the matrix is structurally incomplete.