---
name: test-generation-execution
description: Nucleus V2 Test Generation and Execution baseline. Generates reviewed unit/api/integration test assets and executes approved baseline test commands with .nucleus/tests/** reports.
---

# Test Generation and Execution

> 前置：使用本 Skill 前，先按 `using-nucleus` 完成 Nucleus 入口识别（Claude Code 会话由插件 SessionStart hook 自动注入该纪律）。

本 Skill 用于 Nucleus V2 的测试资产生成与测试执行 baseline。它安装在 Claude Code、Codex 等 coding agent 内部使用，不是 PMS 后端，也不是独立服务。

## 核心原则

测试资产写入和测试命令执行必须先有明确人工审批事实；approval JSON、测试报告和 result package 只能记录证据，不能替代宿主任务、人工审批或质量放行。

<HARD-GATE>
未创建宿主 todo/task 任务包，不得执行 `generate`、`run` 或进入 result package。

缺少 `test-asset-write-approval` 明确审批事实，不得写正式 `tests/**`。

缺少 `test-command` 明确审批事实，不得执行任何测试命令。

请求测试资产写入审批或测试命令审批前，必须先按对应 `subagentPreReview` 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工审批。

测试报告、summary 或 result 不能替代测试资产审批、测试命令审批、人工 review、缺陷创建、PR/MR 审查、合入或发布事实。
</HARD-GATE>

## Checklist

启动本 Skill 后，必须先为以下每一项创建宿主 todo/task，并按顺序执行；Codex 使用计划 / 任务工具，Claude Code 使用 TodoWrite 或等价宿主 todo。每完成、阻塞、等待审批或需要复核一项，都必须逐项更新状态。

1. **读取测试上下文**：读取 `.nucleus/context/<workflowRunId>.json`、primary feature 和 feature development plan；缺关键输入时 `ALERT_AND_BLOCK`。
2. **创建宿主任务包**：把本 checklist 同步成当前会话的宿主 todo/task；未同步前不得生成测试资产或执行命令。
3. **生成测试资产候选**：只生成 `test-asset-candidate.*`，不得直接写正式 `tests/**`。
4. **呈现候选并等待写入审批**：向用户或 PMS 呈现 planned test paths、归属特性和变更范围；缺 `test-asset-write-approval` 时 STOP。
5. **校验测试归属**：确认候选和审批覆盖所有 planned test paths，并校验 `Nucleus.featurePath` 归属。
6. **呈现测试命令并等待审批**：说明 unit / api / integration baseline 命令、cwd 和 argv；缺 `test-command` 时 STOP。
7. **执行 baseline 测试**：只执行已审批且命中 allowlist 的测试命令，并写 `.nucleus/tests/<workflowRunId>/**` report。
8. **写入结果证据**：构建 `.nucleus/runs/<workflowRunId>/result.json`；测试报告和 result 不能替代宿主任务、人工审批或质量放行。

## 边界

- 只支持 `unit`、`api`、`integration` 三类 baseline 测试。
- `generate` 写正式 `tests/**` 前必须读取 `test-asset-write-approval.json`，且 approval 覆盖所有 planned test paths。
- `run` 只读取 `test-command.json` 作为 approval fact，命令必须命中 baseline test runner allowlist，并使用 `shell=False` 执行。
- 测试报告只写 `.nucleus/tests/<workflowRunId>/**`。
- result package 只写 `.nucleus/runs/<workflowRunId>/result.json`。
- 失败或阻塞时 `defectArtifacts=[]`，不得创建缺陷或写 `docs/requirement/**/defects/**`。
- 不 commit、push、创建 PR/MR、merge、release。
- UI/E2E/Playwright 真实执行不属于 baseline。

## 生成测试资产

```bash
python3 skills/test-generation-execution/scripts/test_generation_execution.py generate \
  --repo-root <target-repo> \
  --context <target-repo>/.nucleus/context/<workflowRunId>.json \
  --feature-development-plan <target-repo>/.nucleus/runs/<workflowRunId>/feature-development-plan.json \
  --approval <target-repo>/.nucleus/runs/<workflowRunId>/test-asset-write-approval.json \
  --candidate <target-repo>/.nucleus/runs/<workflowRunId>/test-asset-candidate.json
```

`generate` 会校验唯一 primary feature、feature development plan、approval fact 和 `plannedWrites[]`，只写已声明且已审批的 `tests/**` 文件。每个生成或更新的测试文件前 40 行必须包含：

```text
Nucleus.featurePath: docs/features/.../feature.md
```

## 执行测试命令

```bash
python3 skills/test-generation-execution/scripts/test_generation_execution.py run \
  --repo-root <target-repo> \
  --context <target-repo>/.nucleus/context/<workflowRunId>.json \
  --level unit \
  --command-json <target-repo>/.nucleus/runs/<workflowRunId>/test-command.json
```

`test-command.json` 必须包含：

- `approved=true`
- `approvalType=test-command`
- `approvalFactId`
- `workflowRunId`
- `featurePath`
- `level`
- `sourceFeatureDevelopmentPlanPath`
- `argv`
- `cwd`

## 输出

- `.nucleus/runs/<workflowRunId>/test-asset-candidate.json`
- `.nucleus/runs/<workflowRunId>/test-asset-candidate.md`
- `.nucleus/runs/<workflowRunId>/test-attribution-gate.json`
- `.nucleus/tests/<workflowRunId>/<level>-report.json`
- `.nucleus/runs/<workflowRunId>/result.json`

成功态为 `NEEDS_HUMAN_REVIEW`。失败或证据不足为 `FAILED_BLOCKED`。