---
name: fec-tdd-workflow
description: 用于实现新前端行为、修复 bug 或重构可先由测试描述预期行为的逻辑。适用于组件、hooks/composables、工具函数、API clients、路由守卫或用户工作流；中文触发词包括 TDD、测试驱动、先写测试、红绿重构、回归测试。
---

# 前端 TDD 工作流

## 用途

用“先写失败测试，再实现最小代码，再重构”的节奏交付前端功能，避免只在实现后补覆盖率。

## 流程

1. 识别可观察行为：用户能看到的 UI、组件契约、hook/composable 返回值、路由守卫结果、API client 输出或错误状态。
2. 先写一个最小失败测试：
   - 纯逻辑优先单元测试。
   - 组件交互优先 Testing Library / Vue Test Utils。
   - 跨页关键流程优先 Playwright / Cypress。
3. 运行该测试并确认失败原因正确，失败应来自行为尚未实现，而不是语法、导入或测试环境错误。
4. 写刚好能通过测试的最小实现，不顺手扩大范围。
5. 重新运行测试，确认变绿。
6. 在测试保持通过的前提下重构命名、边界和重复逻辑。
7. 对 bug 修复，保留能复现问题的回归测试。
8. 每轮只扩大一个可观察行为；新需求、新边界和新异常路径各自进入下一轮。

## 证明式测试模式

修复缺陷时先让测试失败，再让它通过。若无法先失败，说明测试没有覆盖原始问题，需要收窄输入、断言或测试层级。

## 前端测试选择

| Risk | Preferred Test |
| ---- | -------------- |
| utils、schema、状态计算 | 单元测试 |
| hooks / composables | 单元或轻量集成测试 |
| 组件 props、emits、交互、状态 | 组件测试 |
| Router、Provider、Store 协作 | 轻量集成测试 |
| 登录、支付、权限、关键 CRUD | E2E 测试 |

## 约束

- 不为了 TDD 引入项目没有使用且收益不清晰的新测试框架。
- 不测试实现细节、私有状态或脆弱 DOM 结构。
- 不把 E2E 当作所有风险的默认答案；优先选择离风险最近的测试层。
- 如果现有仓库没有测试基础设施，先输出最小测试落地建议，再请求用户确认是否引入。
- 不在红灯阶段同时重构；先证明问题，再最小修复，再整理结构。

## 预期输出

- 至少一个先失败后通过的测试覆盖新增或修复行为。
- 实现保持最小范围，重构只在测试通过后进行。
- 总结运行过的测试命令、覆盖的行为和未覆盖风险。
## 纯重构边界

纯粹的保持行为重构，不应人为制造一个失败测试。如果现有行为本身正确、目标只是结构调整，应先建立或补充能够描述“当前行为”的 characterization test，并让它从一开始就是绿色；随后执行 GREEN → REFACTOR → GREEN。只有新增行为或修复会改变行为的缺陷，才使用 RED → GREEN → REFACTOR。