testspec-generate

name	testspec-generate
description	TestSpec 生成测试用例（流程第 4 步）- 根据测试点（specs/*.md）生成完整测试用例并导出 Excel (.xlsx) 或 XMind (.xmind) 格式。当用户要「生成用例」「写测试用例」「导出 Excel」「导出 XMind」「生成测试用例表格」或执行 testspec-generate / testspec generate 时使用。也适用于用户说「把测试点展开成用例」「帮我出一份测试用例表」「生成 Excel 测试文档」的场景。使用内置 Python 脚本完成 Excel/XMind 文件生成，不依赖外部技能。

testspec-generate：用例生成

IRON LAW: Every generated case must be executable, verifiable, and traceable to at least one current TP_ID.

TestSpec Generate Progress:

- [ ] Step 1: Locate current change directory ⚠️ REQUIRED
- [ ] Step 2: Load specs/*.md and upstream context ⚠️ REQUIRED
- [ ] Step 3: Choose strategy and design cases
- [ ] Step 4: Write schema v2 testcases.json
- [ ] Step 5: Run validate_testcases.py ⛔ BLOCKING
- [ ] Step 6: Export Excel/XMind and report outputs

职责

读取当前变更的 specs/*.md（测试点），先根据用户目标选择测试类型策略，再将测试点展开为完整测试用例；最后根据用户指定的格式（Excel 或 XMind）生成测试用例文件，输出到当前变更的 artifacts/ 目录。若存在 strategy.md 可参考其测试类型、层级与通过标准；否则从共享规则源读取默认策略。导出行为必须保持兼容现有脚本和历史产物格式。

当前变更目录

参见 ../_testspec-shared/references/common.md 中的「当前变更目录定位规则」。

共享规则源

• 测试类型策略单一数据源：references/test-type-strategies.md
• 用例设计规则：references/case-design-rules.md
• 输出契约：../_testspec-shared/references/output-contracts.md
• 命名契约：../_testspec-shared/references/naming-contract.md

---

测试点到用例的转换规则

推理式策略选择

按 ../_testspec-shared/references/thinking-protocol.md 执行推理式决策。

上游上下文消费

1. 读取 specs/*.md（必须）
2. 检查上游产物是否包含上下文元数据（<!-- testspec-context ... -->）
3. 若有元数据：
   • 提取 risks_identified → 对风险区域增加异常/边界用例
   • 提取 coverage_estimate → 作为覆盖基线
   • 提取 blocking_open_questions → 相关用例标注风险
   • 提取 testlib_reuse（若有）→ 识别哪些 TP 已在 testlib 中有用例
   • 检查 stale_downstream_artifacts：若命中 testcases.json 或当前输入产物，停止执行并提示先运行 next_skill 或上游 skill rebaseline
   • 检查 source_revision.version：若上游版本高于当前输入产物 context 中记录的版本（或输入产物缺少 source_revision），停止执行并提示上游已更新、需先重跑上游 skill
   • 门禁终止时仅输出：受影响产物名、过期原因（一句话）、建议运行的 skill 名称。不输出分析或部分结果。
   • 提取 regression_tiers（若有）→ 用例继承对应 TP 的回归层级

testlib 参考用例检索

当 testlib 中存在与当前变更相关的已有用例时，读取作为参考以保持一致性：

1. 每次生成前先检查仓库当前工作区中的 testspec/testlib/index.json 是否存在
2. 若存在，通过 testpoints.md 的命名字典匹配 index 中的模块/功能
3. 对匹配到的功能，从对应 <feature>.json 中读取 2-3 条高质量用例（优先 P1/冒烟）
4. 参考用例的作用：
   • 步骤风格一致性：新用例的步骤写法（编号格式、动作动词、粒度）与同模块已有用例保持一致
   • 预期结果格式一致性：验证标准的描述粒度和格式与已有用例对齐
   • 前置条件模式复用：同模块用例的公共前置条件可直接复用
5. 参考用例不影响用例内容设计（场景选择、覆盖策略仍由测试点驱动），仅影响表达风格
6. 若 testlib 不存在或无匹配，兜底走默认生成逻辑（保持兼容）

测试策略推理

通过 3 个核心问题推导测试类型策略，而非关键词匹配：

• ”用户需要什么粒度的测试？”

  • 上线前快速验证 → smoke 策略
  • 完整功能验证 → functional 策略
  • 回归测试 → functional + boundary + exception

• ”哪些场景最容易被遗漏？”

  • 权限交叉、并发操作、状态边界 → 补充对应类型
  • 上游标注的风险区域 → 加深覆盖

• ”冒烟用例应该覆盖哪条业务主线？”

  • 识别最短业务闭环
  • 失败影响最大的功能优先

用户显式指定测试类型时，直接使用，不推理。未指定时默认 functional。策略从 references/test-type-strategies.md 选取，但选择理由来自推理。

推理结论记录

在 testcases.json 的 _context 字段记录推理结论（按 ../_testspec-shared/references/context-protocol.md），包括：

• 常规字段：coverage_estimate, iteration_count, iteration_summary
• testlib 参考信息：testlib_reference.referenced_features（参考了哪些 testlib 功能的已有用例）

转换原则

• 一对多映射：一个测试点可能对应多个测试用例场景
• 场景细化：根据测试点的验证要点，细化为具体的测试场景；涉及多种输入条件或状态时，须设计多个独立用例
• 数据驱动：针对边界验证点，设计多组边界数据的测试用例
• 异常覆盖：针对异常验证点，设计各种异常情况的测试用例
• 优先级独立判断：测试点中的优先级仅供参考，每个用例根据具体场景独立判断；同一测试点可衍生 P1 到 P3 不同级别的用例

验证点类型对应

• 功能验证点 → 正向测试用例（验证功能正常工作）
• 边界验证点 → 边界测试用例（验证临界值处理）
• 异常验证点 → 异常测试用例（验证错误处理）
• 集成验证点 → 集成测试用例（验证模块间交互）
• 非功能性验证点 → 非功能测试用例（性能、安全、兼容性等）

---

用例设计方法

生成用例前加载 references/case-design-rules.md。按测试点特征选择等价类、边界值、判定表、Pairwise、场景法、错误推测或状态迁移；中等及以上复杂度的 TP 额外做创意测试探索，并在 _context 记录新增场景数量。

---

用例类型与冒烟用例

测试类型和策略定义见 references/test-type-strategies.md。冒烟用例是 P1 的核心子集，只覆盖最短业务闭环、阻塞性功能和高频主流程；质量优先于数量。

回归套件层级继承

用例从测试点继承 regression_tier（Smoke / Full / Targeted），作为回归测试选取的分层依据：

• 继承规则：用例的 regression_tier 默认等于其 tp_refs 中最高层级的测试点（Smoke > Full > Targeted）
• 允许降级：Agent 可将复杂测试点的部分衍生用例降级（如 Smoke 测试点的边界用例降为 Full）
• 不允许升级：不得将 Full/Targeted 测试点的用例升级为 Smoke，除非用户显式要求
• 未标注兜底：若上游 testpoints.md 未包含 regression_tier，所有用例默认 Full

---

优先级规则

按风险和业务影响判定优先级，不套固定比例。P1 覆盖核心业务流程、关键入口、阻塞性功能和所有冒烟用例；P2 覆盖常规重要场景；P3 覆盖低频、边缘、体验类场景。

---

用例字段规范

编号

• 格式：{需求名称}_YYYYMMDD{SEQ}
• SEQ：四位数字递增（0001、0002、...）
• 日期使用当前日期，确保同一需求下编号唯一
• 该字段是源用例编号（source id），主要用于当前变更内追溯
• publish 阶段必须结合仓库现状（testlib）执行增量管理，不能假设该编号跨变更稳定

用例标题（与 points 命名契约）

• 用例标题格式：{模块}_{功能点}_{测试场景}
• {模块}、{功能点}必须来自 points 文档的标题层级，禁止使用同义词/缩写/替换词
• 一个测试点可映射多个用例：同一测试点衍生的用例标题必须共享相同前缀
• {测试场景}允许轻量场景词（正确/错误/边界/异常/权限不足/网络超时等），但避免具体数据
• 完整命名规则见 ../_testspec-shared/references/naming-contract.md

用例字段与分组约束（XMind/Excel）

• feature 字段必须等于 {模块}（用于 XMind 分组：{feature} - 测试用例）
• 用例标题的 {模块} 必须与 feature 一致

---

预置条件

• 每个条件带序号，使用换行分隔：1、条件一\n2、条件二
• 无特殊要求时可留空

操作步骤

• 每个步骤带序号，使用换行分隔：1、步骤一\n2、步骤二
• 步骤描述清晰、可执行，包含关键测试数据

测试预期内容

• 每个结果带序号（多个时），使用换行分隔：1、预期一\n2、预期二
• 结果必须具体、可验证，包含关键系统行为和状态变化
• 避免模糊描述（如"正常显示"应改为"显示用户头像，尺寸 200×200 像素"）

tp_refs（测试点追溯）

• 类型：string[]，必填，至少包含 1 个 TP_ID
• tp_refs 只引用当前变更工作区中的测试点，用于追溯 generate 产物来自哪些 TP
• 用例从某个 TP 派生时：tp_refs = [该 TP_ID]
• 若一条用例覆盖多个 TP（同一流程覆盖多个验证点）：
  • tp_refs 包含所有相关 TP_ID
  • 用例的 steps 和 expected_result 必须覆盖每个 TP 的验证要点

期望结果细分原则

复杂的期望结果应拆分为多个验证点，每个验证点设计独立用例：

• 按验证维度拆分（时效性、准确性、完整性、交互反馈等）
• 按验证对象拆分（数据、界面、状态、性能等）
• 按验证时机拆分（即时反馈、后续影响、持久化效果等）

JSON 字符串转义规则

生成 testcases.json 时，所有字符串字段值必须符合 JSON 规范：

• 字段值中的双引号 " 必须转义为 \"
• 反斜杠 \ 必须转义为 \\（\n 换行除外）
• 推荐使用中文引号「」替代双引号包裹 UI 文案，从源头避免转义问题
• 示例："expected_result": "1、按钮文案为\"去完成\"" 或 "expected_result": "1、按钮文案为「去完成」"

---

用例粒度控制

加载 references/case-granularity.md 获取复杂度自适应生成规则、优先级分布、拆分/合并判断标准。

---

反模式识别（Agent 自检参照）

生成 testcases.json 后，对照以下反模式自查。发现符合的情况时自动修正。

反模式	表现	正确做法
复制粘贴预期	所有用例的预期结果都是"操作成功""正常显示"	每个用例的预期必须精确到可验证的具体状态/数值/文案
过度前置条件	前置条件写了 10 行环境配置	前置条件只写与本用例差异相关的条件，公共环境不重复
伪边界	边界用例只是换了一个数值，没有新的验证逻辑	边界用例必须触发不同的系统行为（通过/拒绝/提示）
机械展开	每个测试点都展开相同数量的用例，不考虑复杂度	按复杂度自适应：简单 2-4 条，中等 5-8 条，复杂 8-15 条
场景名无信息	用例标题的场景部分是"测试1""场景A"等无意义命名	场景名反映具体测试意图（"正确凭据登录""密码错误三次锁定"）
孤立用例	用例的 tp_refs 为空，无法追溯到任何测试点	每个用例至少关联 1 个 TP_ID

---

Agentic 自检流程

生成 testcases.json 后，Agent 自主调用校验脚本验证质量，无需等待 review skill。

自检步骤

1. 调用校验脚本：

   python skills/_testspec-shared/scripts/validate_testcases.py \
     --input <变更目录>/testcases.json \
     --testpoints <变更目录>/specs/testpoints.md \
     --pretty
   

2. 解读结果：

   • status: PASS → 直接进入导出步骤
   • status: WARN → 检查 warnings，对高影响项修复
   • status: FAIL → 必须修复所有 errors 后重新生成

3. 自动修复（最多 2 轮）：

   • MISSING_FIELD → 补充缺失字段
   • INVALID_PRIORITY → 修正为合法值
   • DUPLICATE → 合并或区分场景
   • NAMING_FORMAT → 调整为三段式命名
   • 修复后重新调用脚本验证

4. 反模式对照：对照上方反模式表自查，发现符合的情况时修正

5. 覆盖度检查：

   • coverage.pass: true → 继续
   • coverage.pass: false → 补充未覆盖的 TP_ID 对应用例

---

用例质量标准

• 独立性：每个用例可独立执行，不依赖其他用例结果
• 可重复性：可重复执行并得到一致结果
• 可验证性：预期结果具体且可验证
• 清晰性：步骤和预期结果无歧义
• 完整性：包含执行所需的所有信息
• 单一职责：每个用例只验证一个明确的测试点或场景

---

输出格式

• Excel：生成 .xlsx 文件，列头依次为：编号、用例标题、级别、预置条件、操作步骤、测试预期内容、执行结果、执行人、执行日期、备注。
• XMind：生成 .xmind 思维导图（XMind 8 格式，兼容 XMind 桌面版打开），按功能模块组织，叶子节点使用用例标题（优先使用 title，其次 name），包含正向用例、负向用例、边界值用例、异常用例等分类。用例详情节点格式：预置条件：xxx → {级别}操作步骤：xxx（如 P1操作步骤：xxx）→ 期望结果：xxx。

导出契约统一以 ../_testspec-shared/references/output-contracts.md 和脚本/单测为准：skills/testspec-generate/scripts/generate_excel.py、skills/testspec-generate/scripts/generate_xmind.py。如文档表述与实现冲突，必须以脚本与单测为准，不得擅自改动历史格式。

执行步骤

1. 确定当前变更目录（按上规则）。

2. 读取上下文：读取 specs/*.md（必须）；若存在 strategy.md、requirements-analysis.md 或 proposal.md 可一并读取以保持策略与优先级一致，否则按默认策略展开。

3. 从 specs 提取测试用例：解析每个 spec 文件中的测试点，运用上述设计方法和转换规则将其展开为结构化测试用例列表。每个用例包含：

   • 功能/模块（必须来自 points 文档的标题层级 ### {模块}模块；用例字段 feature 必须等于 {模块}）
   • 用例标题（格式：{模块}_{功能点}_{测试场景}；其中 {模块}/{功能点} 必须与 points 标题层级严格一致）
   • 类型：冒烟 / 正向 / 负向 / 边界 / 异常
   • 前置条件、步骤、预期结果
   • 优先级：P1 / P2 / P3

4. 生成 testcases.json（schema v2 格式）：

   顶层为对象，包含 schema_version 和 testcases 数组：

JSON 写入策略

为确保 JSON 格式正确且写入成功：

1. 首选方案：使用当前执行环境的标准文件编辑机制写入 schema v2 对象
2. 兜底方案：如果手写转义风险较高，使用结构化 JSON 序列化方式生成文件，避免手动拼接字符串
3. 验证：python3 -m json.tool testcases.json > /dev/null && echo "JSON OK"

在变更目录或 artifacts/ 下写入临时 testcases.json，供脚本读取。需要字段示例时加载 references/testcases-json-example.md。

注意：字段值中若包含双引号必须转义（\"），推荐用「」替代以避免转义问题。详见「JSON 字符串转义规则」。

5. 调用生成脚本：
   • Excel：执行

     python skills/testspec-generate/scripts/generate_excel.py --input <变更目录>/testcases.json --output <变更目录>/artifacts/<name>_cases.xlsx
     

   • XMind：执行

     python skills/testspec-generate/scripts/generate_xmind.py --input <变更目录>/testcases.json --output <变更目录>/artifacts/<name>_cases.xmind --title "测试用例"
     

6. 保留源文件：默认保留 testcases.json 供 review/publish 复用；仅在用户明确要求时清理临时副本。
7. 告知用户：列出生成的文件路径及简要说明。

---

生成后反思与迭代

替代静态自检清单。按 ../_testspec-shared/references/reflection-protocol.md 执行结构化反思。

Round 1：结构性检查

1. 覆盖度验证：
   • 测试点覆盖率 ≥ 95%（列出未覆盖的 TP_ID）
   • 功能/边界/异常类别是否均有对应用例
2. 优先级分布：
   • 冒烟用例全部为 P1
   • 优先级分布是否合理（纯 P1 或纯 P3 是异常信号，需审视）
   • Agent 自主判断比例是否符合业务风险分布
3. 命名一致性：
   • 用例标题 {模块}_{功能点}_{场景} 格式是否符合
   • feature 字段是否与标题中的 {模块} 一致

Round 2：内容质量检查

以消费者视角（执行测试的人）脑内执行每条用例：

1. 步骤可执行性：步骤是否包含动作动词？是否足够具体到可以直接操作？
2. 预期结果可验证性：是否有模糊表述（"正常显示""操作成功"）？是否有具体的验证标准？
3. 前置条件完整性：执行步骤前需要的状态和数据是否都已说明？
4. 模板化检查：是否有多条用例的步骤/预期结果高度雷同，只是换了个名词？

Round 3：迭代执行

如果 Round 1 或 Round 2 发现问题：

1. 修正发现的具体问题（补充缺失用例、调整优先级、细化模糊描述）
2. 修正后重新验证 Round 1 指标
3. 重新生成 testcases.json 和输出文件
4. 最多迭代 2 轮

迭代可见性

告知用户：

• 本次经过了几轮迭代
• 每轮修正了什么（修正摘要）
• 最终指标（覆盖率、优先级分布、用例总数）

---

依赖

• Excel：需要 openpyxl
• XMind：无额外依赖，使用 XMind 8 格式生成，兼容 XMind 桌面版打开

若 Excel 生成失败且提示缺少 openpyxl，按当前项目的包管理方式安装 openpyxl，不要在未确认的全局环境中直接安装依赖。

产物

• testspec/changes/<name>/artifacts/<name>_cases.xlsx（Excel 格式）
• testspec/changes/<name>/artifacts/<name>_cases.xmind（XMind 格式）

文件名可根据变更名或用户指定调整。