---

name: tdd-workflow description: 在编写新功能、修复 bug 或重构代码时使用此技能。强制执行测试驱动开发，覆盖率 80%+，包括单元测试、集成测试和 E2E 测试。 origin: ECC

测试驱动开发工作流

此技能确保所有代码开发遵循 TDD 原则，具备全面的测试覆盖率。

何时激活

• 编写新功能或新特性时
• 修复 bug 或问题时
• 重构现有代码时
• 添加 API 端点时
• 创建新组件时

核心原则

1. 测试先于代码

始终先写测试，然后实现代码使测试通过。

2. 覆盖率要求

• 最低 80% 覆盖率（单元 + 集成 + E2E）
• 覆盖所有边界情况
• 测试错误场景
• 验证边界条件

3. 测试类型

单元测试

• 独立函数和工具方法
• 组件逻辑
• 纯函数
• 辅助工具

集成测试

• API 端点
• 数据库操作
• 服务交互
• 外部 API 调用

E2E 测试（Playwright）

• 关键用户流程
• 完整工作流
• 浏览器自动化
• UI 交互

4. Git 检查点

• 如果仓库使用 Git，在每个 TDD 阶段后创建检查点提交
• 在工作流完成之前不要压缩或重写这些检查点提交
• 每个检查点提交消息必须描述阶段和捕获的确切证据
• 仅计算当前活动分支上为当前任务创建的提交
• 不要将其他分支、早期无关工作或远程分支历史的提交视为有效检查点证据
• 在将检查点视为满足之前，验证该提交可从当前活动分支的 HEAD 到达且属于当前任务序列
• 推荐的紧凑工作流为：
  • 一个提交用于添加失败测试并验证 RED 状态
  • 一个提交用于应用最小修复并验证 GREEN 状态
  • 一个可选提交用于完成重构
• 如果测试提交明确对应 RED 且修复提交明确对应 GREEN，则不需要单独的证据提交

TDD 工作流步骤

步骤 1：编写用户旅程

As a [role], I want to [action], so that [benefit]

Example:
As a user, I want to search for markets semantically,
so that I can find relevant markets even without exact keywords.

步骤 2：生成测试用例

为每个用户旅程创建全面的测试用例：

describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {
    // Test implementation
  })

  it('handles empty query gracefully', async () => {
    // Test edge case
  })

  it('falls back to substring search when Redis unavailable', async () => {
    // Test fallback behavior
  })

  it('sorts results by similarity score', async () => {
    // Test sorting logic
  })
})

步骤 3：运行测试（应该失败）

npm test
# Tests should fail - we haven't implemented yet

此步骤是强制性的，是所有生产变更的 RED 门控。

在修改业务逻辑或其他生产代码之前，必须通过以下路径之一验证有效的 RED 状态：

• 运行时 RED：
  • 相关测试目标编译成功
  • 新的或更改的测试实际被执行
  • 结果为 RED
• 编译时 RED：
  • 新测试新实例化、引用或执行了有 bug 的代码路径
  • 编译失败本身就是预期的 RED 信号
• 在任一情况下，失败是由预期的业务逻辑 bug、未定义行为或缺失实现引起的
• 失败不是仅由无关的语法错误、损坏的测试设置、缺失依赖或无关回归引起的

仅编写但未编译和执行的测试不算作 RED。

在确认此 RED 状态之前不要编辑生产代码。

如果仓库使用 Git，在此阶段验证后立即创建检查点提交。 推荐的提交消息格式：

• test: add reproducer for <feature or bug>
• 如果复现器已编译、执行并因预期原因失败，此提交也可作为 RED 验证检查点
• 继续之前验证此检查点提交在当前活动分支上

步骤 4：实现代码

编写最少代码使测试通过：

// Implementation guided by tests
export async function searchMarkets(query: string) {
  // Implementation here
}

如果仓库使用 Git，现在暂存最小修复但推迟检查点提交直到步骤 5 验证 GREEN。

步骤 5：再次运行测试

npm test
# Tests should now pass

在修复后重新运行相同的相关测试目标，确认之前失败的测试现在为 GREEN。

只有在有效的 GREEN 结果后才能继续重构。

如果仓库使用 Git，在 GREEN 验证后立即创建检查点提交。 推荐的提交消息格式：