| name | testspec-generate |
| license | MIT |
| description | TestSpec 生成测试用例（流程第 4 步）- 根据测试点（specs/*.md）生成完整测试用例并导出 Excel (.xlsx) 或 XMind (.xmind) 格式。当用户要「生成用例」「写测试用例」「导出 Excel」「导出 XMind」「生成测试用例表格」或执行 testspec-generate / testspec generate 时使用。也适用于用户说「把测试点展开成用例」「帮我出一份测试用例表」「生成 Excel 测试文档」的场景。使用内置 Python 脚本完成 Excel/XMind 文件生成，不依赖外部技能。 |
testspec-generate：用例生成
铁律：每条生成用例都必须可执行、可验证，并可追溯到至少一个当前 TP_ID。
TestSpec 用例生成进度：
- [ ] 步骤 1：定位当前 change 目录 ⚠️ 必需
- [ ] 步骤 2：加载 specs/*.md 和上游 context ⚠️ 必需
- [ ] 步骤 3：选择策略并设计用例
- [ ] 步骤 4：写入 schema v2 testcases.json
- [ ] 步骤 5：运行 validate_testcases.py ⛔ 阻塞
- [ ] 步骤 6：导出 Excel/XMind 并报告产物
职责
读取当前变更的 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/source-provenance.md
测试点到用例的转换规则
推理式策略选择
按 ../_testspec-shared/references/thinking-protocol.md 执行推理式决策。
上游上下文消费
- 读取 canonical source（优先
requirements.md，否则 proposal.md）和直接上游 specs/testpoints.md（必须）
- 按
../_testspec-shared/references/context-protocol.md 比对 canonical revision：
- canonical 有版本，而 testpoints 缺少版本或版本更低：停止并提示先运行
testspec-points
- testpoints 版本高于 canonical：停止并报告版本元数据损坏
- canonical 无版本：按 Legacy 模式继续并告警，不伪造版本
- 现有 testcases 过期表示本 skill 应重新生成，不得提示用户再次运行当前 skill
- 消费 testpoints 上下文：
- 提取
risks_identified → 对风险区域增加异常/边界用例
- 提取
coverage_estimate → 作为覆盖基线
- 提取
blocking_open_questions → 相关用例标注风险
- 提取
testlib_reuse（若有）→ 识别哪些 TP 已在 testlib 中有用例
- 提取
regression_tiers（若有）→ 用例继承对应 TP 的回归层级
- 提取
canonical_source_policy、evidence_sources、questions → 原样传播；代码不可访问不影响生成
- 成功生成后原样传播 canonical envelope，从 stale 列表移除
artifacts/testcases.json，保留 review，并将 next_skill 指向 testspec-review
testlib 参考用例检索
当 testlib 中存在与当前变更相关的已有用例时，读取作为参考以保持一致性：
- 每次生成前先检查仓库当前工作区中的
testspec/testlib/index.json 是否存在
- 若存在，通过 testpoints.md 的命名字典匹配 index 中的模块/功能
- 对匹配到的功能，只读取 2-3 条可用参考：排除
legacy-import + unverified；缺少新版 provenance 的历史用例只参考命名和格式
- 参考用例的作用：
- 步骤风格一致性：新用例的步骤写法（编号格式、动作动词、粒度）与同模块已有用例保持一致
- 预期结果格式一致性：验证标准的描述粒度和格式与已有用例对齐
- 前置条件模式复用：同模块用例的公共前置条件可直接复用
- 参考用例不影响用例内容设计（场景选择、覆盖策略仍由测试点驱动），仅影响表达风格
- 若 testlib 不存在或无匹配，兜底走默认生成逻辑（保持兼容）
测试策略推理
通过 3 个核心问题推导测试类型策略，而非关键词匹配：
-
”用户需要什么粒度的测试？”
- 上线前快速验证 → smoke 策略
- 完整功能验证 → functional 策略
- 回归测试 → functional + boundary + exception
-
”哪些场景最容易被遗漏？”
- 权限交叉、并发操作、状态边界 → 补充对应类型
- 上游标注的风险区域 → 加深覆盖
-
”冒烟用例应该覆盖哪条业务主线？”
用户显式指定测试类型时，直接使用，不推理。未指定时默认 functional。策略从 references/test-type-strategies.md 选取，但选择理由来自推理。
推理结论记录
在 testcases.json 的 _context 字段记录推理结论（按 ../_testspec-shared/references/context-protocol.md），包括：
- canonical revision envelope：source_revision, blocking_open_questions, dynamic_followups, material_quality, stale_downstream_artifacts, stale_reason, next_skill
- 常规字段：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 覆盖低频、边缘、体验类场景。
用例字段、粒度与反模式
执行前读取：
references/case-design-rules.md：字段规范、设计方法、JSON 转义和反模式references/case-granularity.md：复杂度自适应、拆分与合并../_testspec-shared/references/naming-contract.md：标题与模块命名references/testcases-json-example.md：schema v2 示例
不可省略的主契约：
id 在当前变更内唯一；title 使用 {模块}_{功能点}_{场景}；feature 等于模块tp_refs 非空且只引用当前变更 TP；多 TP 用例的步骤和预期覆盖每个引用- TP 的
oracle_scope = indirect 时只断言当前系统可观察产物；out-of-scope 不生成正式用例
- preconditions/steps/expected_result 使用可执行、可验证的编号文本
- 每条原生用例写
origin.kind = testspec-native 和 trust.status = provisional
- JSON 合法转义；生成后必须通过结构校验
校验与迭代
写入用例后，加载 references/generation-quality-loop.md 并运行：
python "<_testspec-shared-skill-dir>/scripts/validate_testcases.py" \
--input <变更目录>/artifacts/testcases.json \
--testpoints <变更目录>/specs/testpoints.md \
--pretty
导出前解决全部错误和未通过的 TP 覆盖。最多执行两轮有证据支撑的修正；warning 必须人工检查，不得自动忽略。
Review 定向返修
用户要求根据 review-report.md 修复时进入 repair 模式：
- 校验 review 与 canonical revision 一致。
- 只消费
status = open 且明确分配给 generate 的 finding；points/analysis finding 必须回到对应上游。
- 只修改 finding 指定的 case IDs，默认保留 ID；未命中范围的用例保持字节级语义不变。
- 在
_context.review_repairs 记录 issue_id、changed_case_ids 和动作摘要。
- generate 不得自行把 finding 标记 resolved；修复后必须重跑 testspec-review。
输出格式
- Excel：生成 .xlsx 文件，列头依次为：编号、用例标题、级别、预置条件、操作步骤、测试预期内容、执行结果、执行人、执行日期、备注。
- XMind：生成 .xmind 思维导图（XMind 8 格式，兼容 XMind 桌面版打开），按功能模块组织，叶子节点使用用例标题（优先使用 title，其次 name），包含正向用例、负向用例、边界值用例、异常用例等分类。用例详情节点格式：
预置条件：xxx → {级别}操作步骤：xxx（如 P1操作步骤：xxx）→ 期望结果：xxx。
导出契约统一以 ../_testspec-shared/references/output-contracts.md 和当前 skill 目录下的 scripts/generate_excel.py、scripts/generate_xmind.py 及单测为准。如文档表述与实现冲突，必须以脚本与单测为准，不得擅自改动历史格式。
执行步骤
-
确定当前变更目录（按上规则）。
-
读取上下文：读取 specs/*.md（必须）；若存在 strategy.md、requirements-analysis.md 或 proposal.md 可一并读取以保持策略与优先级一致，否则按默认策略展开。
-
从 specs 提取测试用例：解析每个 spec 文件中的测试点，运用上述设计方法和转换规则将其展开为结构化测试用例列表。每个用例包含：
- 功能/模块（必须来自 points 文档的标题层级
### {模块}模块；用例字段 feature 必须等于 {模块}）
- 用例标题（格式：
{模块}_{功能点}_{测试场景}；其中 {模块}/{功能点} 必须与 points 标题层级严格一致）
- 类型：冒烟 / 正向 / 负向 / 边界 / 异常
- 前置条件、步骤、预期结果
- 优先级：P1 / P2 / P3
-
生成 testcases.json（schema v2 格式）：
顶层为对象，包含 schema_version、_context 和 testcases 数组。canonical source 有版本时，_context.source_revision 必须与 specs/testpoints.md 完全一致。原生生成写 _context.origin.kind = testspec-native、_context.trust.status = provisional，不得冒充已 review。
JSON 写入策略
为确保 JSON 格式正确且写入成功：
- 首选方案：使用当前执行环境的标准文件编辑机制写入 schema v2 对象
- 兜底方案：如果手写转义风险较高，使用结构化 JSON 序列化方式生成文件，避免手动拼接字符串
- 验证：
python3 -m json.tool <变更目录>/artifacts/testcases.json > /dev/null && echo "JSON OK"
固定写入 <变更目录>/artifacts/testcases.json，不在变更根目录创建第二份副本。需要字段示例时加载 references/testcases-json-example.md。
注意：字段值中若包含双引号必须转义（\"），推荐用「」替代以避免转义问题。详见「JSON 字符串转义规则」。
- 调用生成脚本：
- Excel：执行
python "<testspec-generate-skill-dir>/scripts/generate_excel.py" --input <变更目录>/artifacts/testcases.json --output <变更目录>/artifacts/<name>_cases.xlsx
- XMind：执行
python "<testspec-generate-skill-dir>/scripts/generate_xmind.py" --input <变更目录>/artifacts/testcases.json --output <变更目录>/artifacts/<name>_cases.xmind --title "测试用例"
<testspec-generate-skill-dir> 必须从当前已加载 SKILL.md 所在目录解析为绝对路径。
- 保留源文件：默认保留
artifacts/testcases.json 供 review/publish 复用；仅在用户明确要求时清理。
- 告知用户：列出生成的文件路径及简要说明。
生成后反思
确定性校验后使用 references/generation-quality-loop.md。报告迭代次数、具体修正、最终 TP 覆盖率、优先级分布和用例数量。
依赖
- Excel：需要
openpyxl
- XMind：无额外依赖，使用 XMind 8 格式生成，兼容 XMind 桌面版打开
- 当前 skill 的依赖清单位于
requirements.txt
若 Excel 生成失败且提示缺少 openpyxl，按当前项目的包管理方式安装 openpyxl，不要在未确认的全局环境中直接安装依赖。
产物
testspec/changes/<name>/artifacts/<name>_cases.xlsx（Excel 格式）testspec/changes/<name>/artifacts/<name>_cases.xmind（XMind 格式）
文件名可根据变更名或用户指定调整。
