Back to Details

moai-workflow-tdd

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Test-Driven Development (TDD) Workflow

测试驱动开发（TDD）工作流

Development Mode Configuration (CRITICAL)

开发模式配置（至关重要）

[NOTE] This workflow is selected based on 
.moai/config/sections/quality.yaml
:
yaml
constitution:
  development_mode: hybrid    # or ddd, tdd
  hybrid_settings:
    new_features: tdd        # New code → use TDD (this workflow)
    legacy_refactoring: ddd  # Existing code → use DDD
When to use this workflow:
  • development_mode: tdd
    → Always use TDD
  • development_mode: hybrid
    + new package/module → Use TDD
  • development_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)
[注意] 本工作流根据
.moai/config/sections/quality.yaml
配置选择：
yaml
constitution:
  development_mode: hybrid    # or ddd, tdd
  hybrid_settings:
    new_features: tdd        # New code → use TDD (this workflow)
    legacy_refactoring: ddd  # Existing code → use DDD
何时使用本工作流:
  • development_mode: tdd
    → 始终使用TDD
  • development_mode: hybrid
    + 新包/模块 → 使用TDD
  • development_mode: hybrid
    + 重构现有代码 → 改用DDD（moai-workflow-ddd）
核心区别:
  • 新文件/包（尚未存在）→ TDD（本工作流）
  • 现有代码（文件已存在）→ 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)
测试驱动开发为创建新功能提供了一种规范的方法，在实现前通过测试定义预期行为。
核心循环 - RED-GREEN-REFACTOR:
  • RED：编写一个失败的测试，定义所需行为
  • GREEN：编写最少的代码使测试通过
  • REFACTOR：在保持测试通过的同时改进代码结构
何时使用TDD:
  • 从零开始创建新功能
  • 构建无现有依赖的独立模块
  • 由行为规范驱动开发时
  • 具有明确契约的新API端点
  • 行为已定义的新UI组件
  • 全新项目（少见 - 通常混合模式更佳）
何时不使用TDD:
  • 重构现有代码（改用DDD）
  • 首要目标是保留现有行为时
  • 无测试覆盖的遗留代码库（先使用DDD）
  • 修改现有文件时（考虑混合模式）

Core Philosophy

核心理念

TDD vs DDD Comparison

TDD与DDD对比

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
TDD方法:
  • 循环：RED-GREEN-REFACTOR
  • 目标：通过测试创建新功能
  • 起点：无现有代码
  • 测试类型：定义预期行为的规范测试
  • 结果：带有测试覆盖的可运行新代码
DDD方法:
  • 循环：ANALYZE-PRESERVE-IMPROVE
  • 目标：在不改变行为的前提下改进结构
  • 起点：具有已定义行为的现有代码
  • 测试类型：捕获当前行为的特征测试
  • 结果：结构更优但行为完全一致的代码

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
TDD的黄金准则是必须在实现代码之前编写测试:
  • 测试定义契约
  • 测试记录预期行为
  • 测试立即捕获回归问题
  • 实现由测试需求驱动

Implementation Guide

实施指南

Phase 1: RED - Write a Failing Test

阶段1：RED - 编写失败的测试

The RED phase focuses on defining the desired behavior through a failing test.
RED阶段专注于通过失败的测试定义所需行为。

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
遵循Arrange-Act-Assert模式:
  • Arrange：设置测试数据和依赖项
  • Act：执行被测代码
  • Assert：验证预期结果

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

阶段2：GREEN - 使测试通过

The GREEN phase focuses on writing minimal code to satisfy the test.
GREEN阶段专注于编写最少的代码以满足测试要求。

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

阶段3：REFACTOR - 改进代码

The REFACTOR phase focuses on improving code quality while maintaining behavior.
REFACTOR阶段专注于在保持行为不变的前提下提升代码质量。

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

TDD工作流执行

Standard TDD Session

标准TDD会话

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
通过manager-tdd执行TDD时:
步骤1 - 理解需求:
  • 阅读SPEC文档了解功能范围
  • 从验收标准中识别测试用例
  • 规划测试实现顺序
步骤2 - RED阶段:
  • 编写第一个失败的测试
  • 验证测试因正确的原因失败
  • 记录预期行为
步骤3 - GREEN阶段:
  • 编写最小化实现
  • 运行测试验证其通过
  • 进入下一个测试
步骤4 - REFACTOR阶段:
  • 审查代码以寻找改进点
  • 以测试为安全保障进行重构
  • 提交整洁的代码
步骤5 - 重复:
  • 继续RED-GREEN-REFACTOR循环
  • 直到所有需求都已实现
  • 直到所有验收标准都通过

TDD Loop Pattern

TDD循环模式

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
对于需要多个测试用例的功能:
  • 预先识别所有测试用例
  • 根据依赖关系和复杂度排序
  • 为每个测试用例执行RED-GREEN-REFACTOR
  • 维护累积的测试套件

Quality Metrics

质量指标

TDD Success Criteria

TDD成功标准

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
测试覆盖率（必填）:
  • 每次提交最低80%覆盖率
  • 新代码建议90%覆盖率
  • 所有公共接口均经过测试
代码质量（目标）:
  • 所有测试通过
  • 没有在实现后编写的测试
  • 清晰的测试名称记录行为
  • 满足测试要求的最小化实现

TDD-Specific TRUST Validation

TDD专属TRUST验证

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
将TRUST 5框架应用于TDD场景:
  • 可测试性：测试先行方法确保可测试性
  • 可读性：测试记录预期行为
  • 易懂性：测试作为活文档
  • 安全性：在实现前编写安全测试
  • 透明度：测试失败提供即时反馈

Integration Points

集成点

With DDD Workflow

与DDD工作流集成

TDD and DDD are complementary:
  • TDD for new code
  • DDD for existing code refactoring
  • Hybrid mode combines both approaches
TDD和DDD相辅相成:
  • TDD用于新代码
  • DDD用于现有代码重构
  • 混合模式结合了两种方法

With Testing Workflow

与测试工作流集成

TDD integrates with testing workflow:
  • Uses specification tests
  • Integrates with coverage tools
  • Supports mutation testing for test quality
TDD与测试工作流集成:
  • 使用规范测试
  • 与覆盖率工具集成
  • 支持变异测试以提升测试质量

With Quality Framework

与质量框架集成

TDD outputs feed into quality assessment:
  • Coverage metrics tracked
  • TRUST 5 validation for changes
  • Quality gates enforce standards
TDD输出用于质量评估:
  • 跟踪覆盖率指标
  • 对变更应用TRUST 5验证
  • 质量门强制执行标准

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
测试过于复杂:
  • 拆分为更小、聚焦的测试
  • 一次测试一个行为
  • 对复杂设置使用测试夹具
实现增长过快:
  • 抵制实现未测试功能的冲动
  • 回到RED阶段开发新功能
  • 保持GREEN阶段的最小化
重构破坏测试:
  • 立即回滚
  • 以更小的步骤进行重构
  • 确保测试验证的是行为而非实现

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
当TDD规范被打破时:
  • 停止并评估当前状态
  • 为现有代码编写特征测试
  • 恢复TDD以实现剩余功能
  • 考虑切换到混合模式
版本: 1.0.0 状态: 活跃 最后更新: 2026-02-03