taiyi-test — 测试验证

进入本阶段前请优先读 .taiyi/changes/<slug>/PHASE-CONTEXT.md（~500 tokens），不要全量加载上游工件。

框架集成

本阶段使用以下框架：

框架	用途	何时加载
Harness	阶段门禁与推进（status → continue；legacy：npx taiyi complete）	全程
GStack	browse — 用于 E2E 浏览器测试和截图验证	Round 5（E2E 轮）
Superpowers	verification-before-completion — 完成前全量验证	完成前

OpenSpec / Spec-Kit / OMO 在本阶段不涉及。

前置门禁（Pre-flight）

0.1 上游确认

• dev 阶段已过关（.taiyi/changes/<slug>/.dev-complete 存在且 exitCode: 0）
• 实现代码已通过 TDD 红→绿循环

0.2 Profile 判定

Profile	TEST.md 要求
full	完整覆盖：5 rounds + 6 维回归测试 + 新 file GREP 填空 + Traceability
api/ui	同 full
lite	简化版：跳过 round 4-5，6 维回归可选
spike/micro	跳过本阶段
nano	跳过

0.3 前置检查清单

• .dev-complete 存在且有 GREEN 证据
• 明确项目的测试命令（npm test / pytest / cargo test 等）

---

步骤

工件契约

层	路径	职责
语义真源	test.json	Zod（src/schemas/test.ts）
生成视图	TEST.md	hbs（src/templates/test.hbs）
流程	本 Skill	5 轮 AC 覆盖、6 维回归、Traceability

工作流：实跑测试 → 更新 json 证据 → scripts/taiyi-forge.sh render <slug> test → status → continue。

详见 docs/taiyi/artifact-contract.md。

json 字段（Zod 摘要）

字段	要求
title	测试计划标题
test_plan	≥1 用例；id / description / status（passed/failed/pending）
unit_framework / unit_coverage_target	可选
edge_cases / performance_tests / security_checks	可选
regression_plan / regression_items	可选；6 维回归仪表盘内容
mocking_boundaries	可选；哪些层可 mock
summary / coverage	可选；执行摘要
evidence	有 passed 时推荐填真跑命令

写作指引（填入 json，render 生成 TEST.md）

1. TEST.md 全局结构

# TEST: <slug 标题>

## Overview
| AC | Round | Type | Status |
|----|-------|------|--------|

2. 按 AC 的 5 轮测试

每轮一个 table，AC 编号来自 REQUIREMENT.md：

### Round 1: 功能正确性（AC 正向）
| AC | PR | Test | Priority | Key Assertions |
|----|----|------|----------|----------------|

### Round 2: 边界条件（AC 负面 + 边值）
| AC | PR | Test | Priority | 边界值 |
|----|----|------|----------|--------|

### Round 3: 错误处理（AC 异常路径）
| AC | PR | Test | Priority | Error Handling |
|----|----|------|----------|---------------|

### Round 4: 集成（跨组件）
| AC | PR | Test | Priority | Endpoint / Interaction |
|----|----|------|----------|-----------------------|

### Round 5: 端到端（关键路径 / 用户流程）
| AC | PR | Test | Priority | Flow |
|----|----|------|----------|------|

3. 6 维回归测试仪表盘

每个维度用 3 态表示：✅ 通过 / ❌ 未通过 / ⬜ 不适用

### Regression Dashboard (pre-landing)

| Dimension | Status | Notes |
|-----------|--------|-------|
| D1 完整功能 | ✅ | 21/21 AC passed |
| D2 边界值 | ✅ | null/empty/long/edge |
| D3 性能 | ⬜ | 无性能要求 |
| D4 并发 | ✅ | 新建不冲突 |
| D5 安全 | ⬜ | 无认证逻辑 |
| D6 回滚 | ✅ | 向下兼容 |

4. 新 file GREP 填空 test（强制）

项目中没有测试文件的新文件 → agent 自动 // src/*.ts → 创建一个 skeleton test file：

// tests/__snapshots__/placeholder.md
## GREP 发现的未覆盖文件
### <file path>
- 行号：<range>
- 状态：❌ 未覆盖
- 建议：增加 <N> 个用例覆盖 <功能>

---

5. Run Commands

所有测试命令必须进入 TEST.md：

## 测试执行命令

# 全部测试
$ npm test

# 单元测试
$ npx vitest run tests/unit/

# 集成测试
$ npx vitest run tests/integration/

# 特定测试
$ npx vitest run tests/unit/validation.test.ts

# 覆盖率（可选）
$ npm run test:coverage

6. Traceability 更新

## Traceability (←REQUIREMENT.md)

### AC → Test Coverage
| AC | 覆盖 Round | 测试文件 |
|----|-----------|---------|
| AC-1.1 | R1, R2 | tests/unit/validation.test.ts |
| AC-2.1 | R1, R3, R4 | tests/integration/translate.test.ts |

---

过关（Harness）

1. 逐项检查 ## 质量自检；有未通过项则不要过关。
2. 预检：scripts/taiyi-forge.sh status <slug> --json --compact — 解析 engineTruth（qualityReady / blockers）。
3. 用户确认后过关：scripts/taiyi-forge.sh continue <slug>。
4. 过关后再 status --json --compact，读 engineTruth；若 currentPhase 已变为 review，切换到 taiyi-review Skill 并通知用户。

Legacy：npx taiyi complete <slug> test 仍可用；聊天优先 /taiyi:continue。

产出

• .taiyi/changes/<slug>/TEST.md
• .taiyi/changes/<slug>/test.json

与下游衔接

下游	需要
taiyi-review	Regression Dashboard → review 质量入口；测试通过证据 → review 的 QA 评估；Traceability → 审查收尾证据
taiyi-integration	测试通过 → 归档前提；Traceability → 集成过程中 AC 的 Final Status

异常处理

场景	处理
测试未全部通过	读失败测试输出 → 归类测试 bug vs 实现 bug。实现 bug → DIAGNOSE FIX（最小修复）→ 重跑。测试 bug → 修复测试。最多 3 轮，超限上报用户
AC 未完全覆盖	补充第 2/3 轮测试覆盖缺失 AC，直到所有 AC 至少有一条测试
项目无测试框架	在 TEST.md 中说明，跳过运行但保留 Round table 作为覆盖文档
回归仪表盘有 ❌	不能过关 test 阶段，必须全 ✅ 或 ⬜ 才可通过
continue 被拒	检查 Traceability 是否完整、是否有 ❌ 回归。修复后 status 再 continue
误过关本阶段或后续	scripts/taiyi-forge.sh undo <slug> test

<fatal_constraints>

• NEVER delete tests to make the suite pass — that is gaming the system. Fix the code or fix the test.
• NEVER skip Round 2 (边界条件) — this is where most regressions live.
• NEVER claim "tests pass" without running them — evidence before claims.
• NEVER skip GREP 填空 — every new file needs at least a skeleton test.
• NEVER skip Traceability update from REQUIREMENT.md. </fatal_constraints>

质量自检

• 前置门禁已通过（0.1–0.3）
• 5 轮测试 table 完整（Round 1-5）
• 全部 AC 至少有一条测试
• 6 维回归仪表盘全部 ✅ 或 ⬜
• 新文件 GREP 填空已完成
• 所有测试命令可实际运行（非占位符）
• Traceability（AC→Test Coverage）已更新
• 全部测试通过（实跑证据）

引擎门控（自动，无需手动确认）

• AC 自动扫描: .test.ts 中 AC-XX 引用 → 自动填入 ac_coverage
• AC 覆盖验证: 每条未完成 AC 必须有测试覆盖 → 阻止
• 覆盖率阈值: 单元测试覆盖率 < 80% → 阻止