测试驱动开发（TDD）

概述

适用于所有 TDD 工作流的一项核心技能。强制采用“先写测试”的开发方式，并复用当前代码仓库中已有的模式。支持三种输入模式，分别对应不同入口：规格说明文件（specs）、任务文件（task files）或即兴描述（ad-hoc descriptions），但其核心循环始终为：RED → GREEN → REFACTOR。

输入模式

自动识别输入类型，并进入对应模式：

模式 A：源自规格说明文件（.spec.md）

当输入引用了一个包含 Given/When/Then 验收条件的 .spec.md 文件时使用此模式。

1. 定位并解析该规格文件 —— 提取全部 Given/When/Then 三元组
2. 为每条验收条件生成一个测试存根，主体为 todo!()：

   /// Spec:  — Criterion #
   /// Given 
   /// When 
   /// Then 
   #[test]
   fn _criterion__() {
       todo!("Implement: ");
   }
   

3. 验证存根可编译但运行失败：cargo test --no-run -p
4. 进入 TDD 循环，使各存根通过测试

程序化支持： ralph_core::preflight::{extract_acceptance_criteria, extract_criteria_from_file, extract_all_criteria} 可用于从规格文件中解析验收条件。

模式 B：源自任务文件（.code-task.md）

当输入引用了 .code-task.md 文件或某项具体实现任务时使用此模式。

1. 阅读任务描述，明确其中的验收条件或需求
2. 发现已有模式（参见“模式发现”章节）
3. 设计测试场景，覆盖正常流程、边界情况及错误条件
4. 在任何实现代码编写前，先编写所有失败的测试
5. 进入 TDD 循环

模式 C：源自描述性文本

适用于无规格说明文件或任务文件的即兴任务。

1. 从描述中厘清需求
2. 发现已有模式（参见“模式发现”章节）
3. 编写失败的测试，聚焦于所描述的行为
4. 进入 TDD 循环

模式发现

编写测试前，应先探查代码库中已有的约定：

rg --files -g "crates/*/tests/*.rs"
rg -n "#[cfg(test)]" crates/

通读目标代码附近 2–3 个相关测试文件，并在新测试中复现以下惯例：

• 测试模块的组织结构、命名方式与断言风格
• 测试夹具（fixture）辅助函数与工具函数
• tempfile、预设场景（scenarios）或测试框架（harnesses）的使用方式

TDD 循环

1) RED —— 测试失败

• 编写精确覆盖所需行为的测试
• 运行测试，确认其因预期原因而失败
• 若未实现功能时测试即通过，则该测试不正确

2) GREEN —— 最小实现

• 仅编写足以让测试通过的最少代码
• 此阶段不得添加额外功能，也不得进行重构

3) REFACTOR —— 重构优化

• 在确保测试持续通过的前提下，改进实现逻辑与测试代码
• 使其与周边代码库的规范保持一致
• 每次修改后均需重新运行测试

Proptest 使用指南

仅当同时满足以下全部条件时，方可使用 proptest：

• 函数为纯函数（无 I/O、无时间依赖、无全局状态）
• 对给定输入，输出确定且可重现
• 输入空间复杂或存在大量边界情况

proptest! {
    #[test]
    fn round_trip(input in "[a-z0-9]{0,32}") {
        let encoded = encode(input.as_str());
        let decoded = decode(&encoded).expect("should decode");
        prop_assert_eq!(decoded, input);
    }
}

除非具备充分理由，否则不得将 proptest 作为新依赖引入项目。

背压集成（Backpressure Integration）

在完成事件中包含覆盖率证据：

ralph emit "build.done" "tests: pass, lint: pass, typecheck: pass, audit: pass, coverage: pass (82%)"

在可行时，运行 cargo tarpaulin --out Html --output-dir coverage --skip-clean。若无法运行覆盖率分析，请说明原因，并提供针对性的测试证据作为替代。

测试位置规则

• 单个规格说明映射到单一模块 → 在模块内使用 #[cfg(test)] 内联测试
• 单个规格说明横跨多个模块 → 在 crates//tests/ 下编写集成测试
• CLI 行为测试 → 放入 crates/ralph-cli/tests/
• 始终遵循目标 crate 中已有的测试组织模式

反模式（Anti-Patterns）

• 先写实现代码，再补测试
• 生成无需实现即可通过的测试
• 直接复制其他 crate 的测试，未适配本地模式
• 对于简单场景，本可用示例测试（example test）解决，却强行引入 proptest
• 在缺少覆盖率证据的情况下发出完成事件