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

moai-workflow-tdd

Original

Translation

Test-Driven Development (TDD) Workflow

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

Development Mode Configuration (CRITICAL)

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

Quick Reference

快速参考

Core Philosophy

核心理念

TDD vs DDD Comparison

TDD与DDD对比

Test-First Principle

测试先行原则

Implementation Guide

实施指南

Phase 1: RED - Write a Failing Test

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

Writing Effective Tests

编写有效测试

Test Structure

测试结构

Verification

验证

Phase 2: GREEN - Make the Test Pass

阶段2：GREEN - 使测试通过

Minimal Implementation

最小化实现

Verification

验证

Phase 3: REFACTOR - Improve the Code

阶段3：REFACTOR - 改进代码

Safe Refactoring

安全重构

Continuous Verification

持续验证

TDD Workflow Execution

TDD工作流执行

Standard TDD Session

标准TDD会话

TDD Loop Pattern

TDD循环模式

Quality Metrics

质量指标

TDD Success Criteria

TDD成功标准

TDD-Specific TRUST Validation

TDD专属TRUST验证

Integration Points

集成点

With DDD Workflow

与DDD工作流集成

With Testing Workflow

与测试工作流集成

With Quality Framework

与质量框架集成

Troubleshooting

故障排除

Common Issues

常见问题

Recovery Procedures

恢复流程