test-case-generation

name: test-case-generation version: 1.4.0 description: >- 根据 PRD、TRD、设计稿先生成 XMind 检查点，再生成全新测试用例，并在用户提供历史用例时生成历史结合版用例。 适用于需求评审检查点梳理、全新用例生成、历史用例复用更新、Google Sheet 或 Excel 测试用例输出。 author: tingting.liutt@shopee.com metadata: team: QA category: qa-skills tags: [test-case-generation, xmind, jira, google-sheets, excel]

需求驱动的测试用例生成

前置信息收集

用户只需提供 Jira 需求号，其余信息优先从 Jira 自动获取，获取不到再向用户询问。

自动获取流程

1. 使用 MCP user-project-buddy-mcp 的 get_jira_issue 读取 Jira，提取以下字段：

get_jira_issue(issueNumber="SPXFM-215194", fields=["Summary", "Description", "Status", "Assignee"])

2. 从 Description 中提取链接（按关键字匹配，不区分大小写）：

提取规则（按优先级依次尝试）：

1. 关键字: https://... 或 关键字：https://... — 取 : / ： 后的 URL
2. 关键字=https://... — 取 = 后的 URL
3. [关键字](https://...) — 取 () 内的 URL（忽略 [] 内的 URL）
4. 关键字 https://... — 取空格后的 URL

3. 提取到的 URL 必须保留原始字符（含 +、% 等），不得丢失或转换

用户需补充的信息

Jira 中获取不到或不存在的信息，再向用户询问：

工作流程

严格按以下阶段执行。最终产物固定为三份：

1. XMind 检查点：面向评审，按页面/功能拆检查点和疑问点；必须输出可打开的 .xmind 文件。
2. 需求全新用例：只根据已确认的 XMind 生成，新增用例 ID 留空。
3. 历史用例 + 全新用例结合版：用户提供历史用例时生成，复用历史 ID，未覆盖场景新增。

关键关卡：XMind 必须先给用户检查并完成调整，用户确认后再生成用例。用户明确要求跳过时才直接生成用例。

第一步：收集需求输入并读取源文档

1. 使用 MCP user-project-buddy-mcp 的 get_jira_issue 获取需求信息
2. 从 Description 中提取 PRD 链接，获取不到则向用户询问
3. 使用 MCP user-Confluence communication server 的 search 或 get_page 读取 PRD
4. 从 Jira Description 或用户输入提取 TRD、Figma、历史用例和输出位置
5. 读取 TRD 时只纳入用户关注范围；算法内部、Metrics、平台配置等用户明确不测的内容，只保留备注，不生成 QA 用例
6. 读取 Figma 时必须以页面结构、字段、筛选项、按钮、弹窗、log/edit 分区为准，不得根据经验补 UI

输出：源文档读取结果，列出 PRD / TRD / Figma / 历史用例是否已获取。

第二步：生成源文档覆盖矩阵

将 PRD、TRD、Figma 合并为覆盖矩阵：

处理规则：

• PRD、TRD、Figma 已给出明确答案时，按明确答案写入矩阵和后续 XMind。
• 只有三份源文档都缺失，或源文档之间互相冲突时，才标为疑问。
• 疑问要挂在对应页面/功能节点下，并用红色或 🔴【疑问】 标识，禁止单独拉一个“待确认问题”目录。
• 范围外内容要挂在对应节点下，标记 【保留但不主测】，禁止直接删除导致评审看不到边界。

输出：源文档覆盖矩阵，作为 XMind 的唯一输入。

第三步：生成 XMind 检查点

XMind 用于需求评审，必须按页面功能组织，避免按接口堆点。

硬性输出要求：

• 第一步检查点产物必须是实际 .xmind 文件，禁止只输出 Markdown、纯文本、截图或“同等层级结构”代替。
• .xmind 必须使用当前 XMind 客户端可打开的 JSON 包格式：zip 内包含 content.json、metadata.json、manifest.json。
• 不要生成旧版 content.xml / styles.xml / META-INF/manifest.xml 格式；这类文件在当前环境容易打不开。
• 生成前可先把检查点组织成缩进大纲作为中间变量或临时文件，但交付给用户的检查点文件必须是 <需求号或pageId>-xmind-checkpoints.xmind。
• 使用本 skill 自带脚本生成文件：

python3 ai-skills/qa-skills/test-case-generation/scripts/generate_xmind.py \
  --outline <outline.txt> \
  --output <需求号或pageId>-xmind-checkpoints.xmind \
  --title "<需求号> XMind 检查点" \
  --root-title "<需求名 / Jira>"

生成后必须校验：

unzip -t <需求号或pageId>-xmind-checkpoints.xmind
python3 ai-skills/qa-skills/test-case-generation/scripts/generate_xmind.py \
  --validate <需求号或pageId>-xmind-checkpoints.xmind

推荐层级：

需求名 / Jira
  页面 / 模块
    页面分区或功能区
      功能
        场景检查点
      筛选项
        场景检查点
      列表
        场景检查点
      新增 / 编辑 / 删除 / Log
        场景检查点
      接口与数据流
        入参检查
        出参处理
        异常和兼容

XMind 规则：

• 按实际页面拆，例如 Default Configuration 和 Custom Configuration 独立时要分开写。
• 筛选项、列表、按钮、弹窗、Edit、Log 放在设计稿所在页面下。
• 每个页面/模块可放一个“接口与数据流”节点，用于验证前端/后端/服务传参、落库、返回处理。
• 涉及算法时，QA 关注“开发传给算法的参数是否正确”和“算法返回后系统是否正确接收、落库、展示、流转”；算法内部策略标 【保留但不主测】。
• 设计稿没有的字段、选项、筛选方式不能硬写；PRD/TRD 已明确的内容可以写入，不额外制造疑问。
• 功能不要区分“历史”和“本次”，都按这个需求上线后需要关心的场景组织。
• 用户明确不写 case 的内容，例如开发自测的 Metrics，不进最终用例；如需保留边界，只在对应节点备注。

输出：可打开的 .xmind 检查点文件，并把文件路径发给用户检查。

第四步：等待用户检查 XMind

用户检查 XMind 后，按反馈迭代：

• 用户指出某节点不符合 PRD/TRD/Figma 时，回源文档核对后修改。
• 用户指出漏点时，补到对应页面/功能下，顺带复查同类模块是否也漏。
• 用户要求删除单独疑问目录时，把疑问拆回对应模块。
• 用户确认 XMind 完成后，再进入测试用例生成阶段。

输出：已确认的 XMind。后续用例只能基于这份 XMind 生成。

第五步：根据 XMind 生成需求全新用例

全新用例只覆盖已确认 XMind 中 QA 要测的节点：

• 新增用例 id 列必须留空。
• 用例按页面/功能组织，避免平铺成接口清单。
• 每个页面/模块可以有接口场景，但接口场景要挂在对应模块下。
• 步骤和预期必须一一对应，编号一致。
• 步骤写操作，预期写可验证结果；不要把改动点塞进备注。
• 仍未确认的疑问点，只在 XMind 保留；生成用例时需写成可执行场景或暂不生成。
• Jira key 只填真实 Jira 号，例如 SPXFM-235663；Confluence pageId 禁止伪造成 Jira key。
• 用例tag 默认留空，除非用户或团队模板明确要求。

输出：需求全新用例 Sheet / Excel，例如 <需求号或pageId>-xmind-new-cases。

第六步：处理历史用例并生成结合版（如有）

当用户提供历史用例时，基于“已确认 XMind + 需求全新用例 + 历史用例”生成一份新的结合版 Sheet / Excel。

6.1 读取历史用例

1. 使用 openpyxl 读取 .xlsx 文件
2. 如历史用例在 Google Sheet，读取用户指定的历史 sheet，不改原 sheet
3. 解析表头确认列定义（以历史文件为准，可能 20 列、24 列或 25 列）
4. 提取所有用例的 ID、分类层级（L4~L7）、名称、步骤

6.2 识别重叠用例

将历史用例与 XMind 叶子节点匹配，分为三类：

6.3 核心原则

• ID 复用：重叠用例必须使用历史 case_id，导入时会自动更新原用例
• 层级保留：更新的历史用例保留其原始 L4/L5/L6/L7 分类，不改为新的分类
• 标记更新：是否需要更新 列标记为 "是"
• Jira key 追加：更新历史用例时，Jira key 列保留原有值，在后面追加当前需求号，用逗号分隔（如 SPXFM-179094,SPXFM-215194）
• 历史优先：历史用例已覆盖的场景，必须在历史用例上修改，禁止新增重复用例
• 仅新增未覆盖场景：只有历史用例完全没有覆盖的全新功能/场景，才新增用例
• 禁止改原始 sheet：原历史 sheet 和需求全新用例 sheet 不改，结合版输出到新的 sheet / 文件
• 禁止额外 diff 列：不要通过新增列解释改动点，改动点直接写进步骤和预期
• 备注少用：不要在备注列写“本次新增/修改”；这些内容放入步骤和预期。备注只放真实执行说明。

6.4 历史用例内容更新策略（重要）

根据新需求与历史用例的关系，采用不同的更新方式：

逻辑冲突示例（直接改写）：

历史用例 有线上支付弹窗，线上支付弹窗展示 原有内容：

步骤：1. 骑手扫描该订单，点击 Delivered
预期：1. 弹出线上支付弹窗，默认支付方式 "Recommend"，显示 Online Payment, Cash

新需求将 Online Payment 替换为 VietQR，这是逻辑冲突，应直接改写：

步骤：1. 骑手扫描该订单，点击 Delivered
预期：1. 弹出 Collect Payment 页面，VietQR 默认选中带 Recommend 标签，Cash 可选

补充场景示例（增量追加）：

历史用例 Proof 页面显示 ASF 原有内容：

步骤：1. 进入 Proof 页面  2. 查看 ASF 金额展示
预期：1. ASF 金额正确  2. 格式为 "ASF XX VND"

新需求新增了 Amount Collection Status 字段，这是补充场景，应追加：

步骤：1. 进入 Proof 页面  2. 查看 ASF 金额展示  3. 查看 Amount Collection Status
预期：1. ASF 金额正确  2. 格式为 "ASF XX VND"  3. 根据收款状态展示 Pending Collect / Collected

建议追加格式：

<历史原步骤>

1. [<Jira>新增：<新增检查点标题>] <本次新增操作>
2. <本次新增操作>

<历史原预期>

1. [<Jira>新增：<新增检查点标题>] <本次新增预期>
2. <本次新增预期>

历史合并验算：

• 结合版中所有非空 ID 都能在历史 sheet 找到。
• 非冲突更新的历史用例，原步骤和原预期必须保留在本次新增内容前面。
• 冲突更新需要能说明被替换的是哪一段旧逻辑，禁止整条历史用例重写。
• 原历史 sheet、全新用例 sheet 不被改动。

第七步：生成 Excel / Google Sheet

分类体系（六级分类）

每个分类都必须覆盖，无对应场景则标注原因：

用例编写原则

1. 可执行性优先：每条用例必须可由测试人员直接执行，避免过于抽象
2. 合并同类项：相似场景合并为一条用例，避免冗余（如 3 种费用类型合并为 1 条）
3. 一条用例一个验证点：通过前置条件控制变量
4. 步骤和预期一一对应：步骤编号与预期结果编号对应
5. 具体而非笼统：
   • 按钮颜色写色值（如 #EE4D2D）
   • 文案写原文（如 "No Search Result"）
   • 金额写具体值（如 COD 80 VND + ASF 20 VND = 100 VND）
6. 来源一致：字段名、选项、筛选方式以 PRD/TRD/Figma 明确内容为准，禁止根据经验补不存在的选项
7. 页面优先：评审用例按页面功能写，接口检查点挂在对应页面/模块下

优先级分配

默认不使用 P0，除非用户明确要求。

使用 Google Sheet 或 Python openpyxl 生成文件，优先遵循用户指定输出位置。

1. 生成或更新 XMind 检查点
2. 创建需求全新用例 sheet / Excel
3. 如有历史用例，创建历史结合版 sheet / Excel
4. 输出统计信息（总数、新增数、更新数、优先级分布、页面/模块分布）

命名规则：

• XMind：<需求号或pageId>-xmind-checkpoints.xmind
• 需求全新用例：<需求号或pageId>-xmind-new-cases
• 历史结合版：<需求号或pageId>-merged-final-cases

列定义和代码模板：详见 references/excel-template.md

脚本结构要求：

def add_case(l4, l5, l6, l7, name, precondition, steps, expected, priority,
             tags="", remark="", l8="", l9="", case_id=None, need_update="",
             jira_key=None):
    """
    case_id: 仅更新历史用例时传入历史 ID；新增用例不传（id 列留空）
    need_update: "是" 表示这是更新的历史用例
    jira_key: 默认使用当前真实 Jira；历史结合版传入“历史 Jira + 当前 Jira”
    """

ID 规则（重要）：

• 新增用例：id 列必须留空，不能随机生成，由用例库导入时自动分配
• 更新历史用例：id 列填写历史用例的原始 ID，导入时会覆盖更新

# 需求全新用例 — 不传 case_id，id 列留空
add_case(L4_NEW, L5_NEW, "00-全流程检查", "", ...)

# 历史结合版中的复用用例 — 传入历史 case_id
add_case("Delivery", "Single Delivery", "", "", ..., case_id="a-2754-2446c", need_update="是")

第八步：最终验算和交付

交付前必须做一轮验算：

1. 源文档覆盖：PRD/TRD/Figma 覆盖矩阵中的主测项，都能在 XMind 找到对应节点。
2. XMind 到用例覆盖：XMind 中每个 QA 主测叶子节点，都有用例覆盖；范围外节点有备注说明。
3. XMind 文件可打开性：.xmind 通过 unzip -t，并通过 scripts/generate_xmind.py --validate 校验，包内包含 content.json、metadata.json、manifest.json。
4. 设计稿一致性：字段、筛选项、按钮、列表列名、枚举值没有凭经验补写。
5. 历史合并完整性：非冲突历史用例保留原步骤/预期，并在后面追加本需求检查点。
6. 表格卫生：无临时辅助列、无残留公式、无多余 diff 列、无无效 Jira key、无用户未要求的 tag。
7. 可执行性：步骤和预期编号一一对应，单条用例不啰嗦、不平铺。
8. 输出统计：分别统计 XMind 节点数、全新用例数、结合版新增/更新数。

工具依赖

注意事项

• Confluence 403：直接 URL 可能 403，改用 search → get_page 方式
• Figma 节点：URL 中的 node-id 参数用于定位具体设计节点
• XMind 格式：第一阶段必须交付可打开的 .xmind，zip 内使用 content.json、metadata.json、manifest.json；生成后必须执行 unzip -t 和脚本 --validate
• 历史用例列数：以历史文件实际列数为准（可能 20 列、24 列或 25 列），生成文件必须与之对齐
• 脚本可重复运行：生成的 Python 脚本应支持重复运行，每次覆盖输出
• 用例数量：按需求功能点完整覆盖，不人为限制数量；但应合并相似场景避免冗余
• 历史合并：默认追加本需求检查点；只有旧逻辑与新逻辑冲突时才改写冲突段
• Jira key：只使用真实 Jira key，禁止写 CONFLUENCE-<pageId>
• 用例 tag：默认留空，禁止自动塞功能名、模块名、权限、更新等泛化标签

Reference

• Excel 列定义与代码模板：详见 references/excel-template.md

SKILL_USAGE_START This skill must call the usage report API exactly once after the skill execution is completed. POST https://ai-management.ssc.test.shopee.io/api/v1/skill-usage/report Body: {"skill_name":"test-case-generation"}