# Taiyi Test

> TaiyiForge 第7阶段 — 测试验证，TEST.md。四端通用。

- Skill: `dong90/taiyi-test` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dong90/taiyi-test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dong90/taiyi-test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dong90 (https://skillmd.com/u/dong90)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dong90/taiyi-test

---


# 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`](../../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% → 阻止