test-case-management

一个手动测试用例写着“测试登录”，预期结果是“确认能正常工作”，却能通过每次评审，什么问题也发现不了——两个测试人员执行方式不同，谁也无法判断测试是否失败。本技能会生成确定性用例（离散步骤、每个步骤各有一个可观察的预期结果、具体测试数据），将它们整理成便于导航的套件，并为 TestRail、Xray Cloud、Zephyr Scale 和 Qase 生成符合各工具要求的 API/CSV 载荷——这些工具的 API 看似相似，却使用不同的身份验证方案、端点和步骤字段名称，Agent 经常会将它们混淆。

快速导航

请求	前往
根据 AC 编写一个规范的用例	测试用例剖析
根据用户故事批量生成用例	批量编写 + 工具章节
“检查这些步骤／是否可验证？”	模糊步骤检查 + references/linting.md
TestRail / Xray / Zephyr / Qase API 载荷	工具载荷 + references/tool-apis.md
导入 TestRail 的 CSV	references/import-and-traceability.md（CSV 章节）
整理套件／章节	references/import-and-traceability.md（整理）
需求 ↔ 测试、覆盖缺口	可追溯性 + references/import-and-traceability.md
手动测试 → 自动化决策	自动化进阶

发现问题

首先，检查项目根目录中的 .agents/qa-project-context.md，了解所用工具、项目键和约定；跳过其中已有答案的问题。如果该文件不存在，建议使用 qa-project-context 技能创建。然后澄清以下问题：

• 使用哪种工具——TestRail、Xray、Zephyr Scale 还是 Qase？ 每种工具的 API 身份验证方案、端点格式和步骤字段名称都不同。弄错会导致载荷返回 401 或 400 错误。
• 仅限 TestRail：使用单一仓库模式还是多个套件？ 这会决定用例是放在一个套件的各个章节下，还是分属不同套件，并影响每个 section_id 和组织方案。
• 仅限 Xray／Zephyr：使用 Jira Cloud 还是 Server/DC？ Cloud 和 Server 使用不同的基础路径和身份验证方式。本技能面向 Cloud；Server 使用不同的端点。
• 用例的来源是什么——验收标准、用户故事，还是自由格式的功能描述？ 这会影响要生成的用例数量，以及规则的拆分方式。
• 是否需要需求可追溯性？ 如果需要，请现在记录 Jira／需求问题键，以便在创建用例时建立关联，而不是事后补录。

核心原则

1. 预期结果必须能够确定性地检查。 第二个人（或机器）必须无需猜测就能判断通过或失败。“能用”“看起来没问题”“挺好”“等一会儿”都不符合要求。请明确指出确切值、指定元素及其状态、具体消息、状态码、数量或有时间范围的条件。

2. 每个步骤只做一项断言。 每个步骤都只有一个预期结果。在一个步骤中塞进三项检查，会让失败原因变得模糊，无法确定是哪项检查出了问题，也不清楚应该重跑哪项。

3. 每条业务规则对应一个用例，而不是一个大用例。 “有效代码可降低总金额／过期代码报错／已使用代码被拒绝”是三个用例，各自有独立的通过或失败判定，而不是一个写着一大段预期结果的用例。

4. 以工具的 API 为规范——不要混用这四种工具。 TestRail 的 custom_steps_separated、Qase 的 Token 头、Xray 的两步 GraphQL 身份验证，以及 Zephyr 单独的 teststeps 调用，不能互换。请从对应工具的章节复制。

5. 可追溯性的作用是找出尚未覆盖的内容。 交付物应是原生覆盖率报告中没有关联测试的需求列表，而不是一份会过时的电子表格，也不是“每个测试都关联了某项内容”。

6. 按投资回报率自动化，而不是追求数量。 能力有限时，应优先将稳定、高频的回归／冒烟用例纳入自动化；探索性、一次性以及变动频繁／易波动的用例则保留为手动测试。“全部自动化”会把资源浪费在最不适合自动化的候选用例上。

---

测试用例的构成

一条规范的手动测试用例包含五个部分。每个部分都不可缺少；缺少前置条件或测试数据的用例无法复现。

部分	内容	缺少时的问题
标题	功能 — 场景 — 预期结果，单行	无法搜索、重复
前置条件	说明测试所假设的状态（账户已存在、位于 X 页面、功能标志已开启）	测试人员只能猜测设置方式；结果不稳定
步骤	离散操作，每个步骤一项操作	无法复现
预期结果	每个步骤对应一个可观察的后置条件	无法验证
测试数据	使用的具体值（代码、电子邮件、数量、时长）	无法重复

不佳示例（步骤含糊、预期结果无法验证、没有前置条件、没有测试数据）：

Title: Login test
Steps: Test the login.
Expected: Verify it works.

良好示例 — 来自验收标准“连续 5 次密码错误后，账户锁定 15 分钟”：

Title: Login — account locks for 15 minutes after 5 failed attempts
Preconditions: A registered account exists for [email protected]. The user is logged out
               on the /login page. Lockout policy: 5 attempts, 15-minute lockout.
Test Data: email [email protected], wrong password "WrongPass!", correct password "Passw0rd!"
Steps (one assertion per step / single expected result each):
  1. Action:   Submit the login form with [email protected] and "WrongPass!".
     Expected: Error "Invalid email or password." shows; the failed-attempt count is now 1.
  2. Action:   Repeat the wrong-password submit until 5 failed attempts total.
     Expected: On the 5th failure the account is locked; message reads
               "Account locked. Try again in 15 minutes."
  3. Action:   Immediately submit with the CORRECT password "Passw0rd!".
     Expected: Login is still blocked; the same lockout message is shown (lockout overrides
               valid credentials).
  4. Action:   Wait 15 minutes, then submit with the correct password.
     Expected: Login succeeds and the dashboard loads.

注意：前置条件明确、测试数据具体（尝试 5 次、锁定 15 分钟）、步骤清晰离散，并且每个步骤都只有一个确定性的预期结果。

---

根据用户故事批量编写

给定一个用户故事或一组验收标准，先按规则拆分为多个用例，再生成对应工具的专用负载。以下是折扣码用户故事的示例（有效码降低总金额／过期码报错／已使用的码被拒绝）→ 三个用例：

1. 使用有效代码 → 总金额降低（正常流程）。
2. 使用过期（无效）代码 → 显示行内错误，总金额不变。
3. 使用已使用／已兑换的代码 → 被拒绝，总金额不变。

如果团队需要覆盖边界情况，也应添加用户故事中隐含但未明确说明的常见负面情况（空代码、格式错误的代码）。每个用例都要包含离散步骤，并且每个步骤只有一个预期结果——绝不能用一个大用例覆盖全部三条规则。对于一个迭代中要测试哪些内容的范围决策，请参阅 test-planning，而不是本技能。

---

歧义步骤检查

收到“检查”测试套件的请求时，你的任务是标记非确定性步骤并重写它们——而不是认同它们“看起来没问题”。本节要防止的正是这种一味附和的失败模式（敷衍地认定“一切正常”）。

如果无法确定性地验证某个步骤的预期结果，该步骤就有问题。请标记以下任何情况：

• 操作含糊——“随便点点”“测试一下 X”“试试看” → 指明确切的元素和操作。
• 数据含糊——“一些数据”“一个值”“一些内容” → 提供具体的测试数据。
• 预期结果不可观察——“一切正常”“看起来没问题”“没问题”“没有问题” → 指明确切的可观察结果。
• 等待时间无上限——“等一下”“过一会儿” → 设定时间上限（“10 秒内”／“直到加载动画消失且出现一行记录”）。
• 一个步骤包含多个断言 → 拆分为每步一个断言。

对于经典的四步坏测试套件（“应用打开／一切正常／看起来没问题／报告已就绪”），四步都有歧义，必须标记并重写，明确指定选择器、精确值和有上限的条件——绝不能返回“未发现问题”。完整的检查清单、这四个步骤的重写示例以及检查输出表格格式，见 references/linting.md。

---

工具载荷

这四种工具很容易混淆。摘要如下——完整的 curl／GraphQL 请求体见 references/tool-apis.md：

工具	身份验证	创建端点	Steps 字段
TestRail	Basic email:api_key	POST add_case/{section_id}	custom_steps_separated 数组，元素为 {content, expected}
Xray Cloud	POST /api/v2/authenticate → Bearer 令牌	在 /api/v2/graphql 上调用 GraphQL createTest	steps[] {action, result}；Gherkin → testType: Cucumber + gherkin
Zephyr Scale Cloud	Authorization: Bearer <JWT>	POST /v2/testcases，然后 POST /v2/testcases/{key}/teststeps	单独调用 teststeps，内嵌 {description, expectedResult, testData}
Qase	请求头 Token: <key>	POST /v1/case/{CODE}/bulk	steps[] {action, expected_result, data}

参考文档中说明的特定工具陷阱必须遵守：

• TestRail——分步内容必须使用 custom_steps_separated（而不是普通的 custom_steps 文本块）；端点是 add_case/{section_id}（而不是用于测试运行实例的 add_test）。基础路径是 {instance}/index.php?/api/v2。不要使用 Qase 风格的 POST /case。
• Xray Cloud——先进行身份验证（使用 client_id/client_secret 调用 /api/v2/authenticate，获取有效期为 24 小时的 Bearer 令牌），然后优先使用 GraphQL createTest。导入 Gherkin 时，测试类型必须是 Cucumber，而不是 Generic。避免使用已弃用的 Cloud 路径 /rest/raven/1.0/...、Server 风格的 REST，以及 Jira 用户名／密码 Basic 身份验证。
• Zephyr Scale Cloud——基础路径是 api.zephyrscale.smartbear.com/v2，使用 JWT Bearer。步骤必须通过单独的 /testcases/{key}/teststeps 调用提交，不能作为文本块放在创建请求体中。不要输出 /v1/、错误的主机名或 Qase 的 Token 请求头。
• Qase——身份验证方式是 Token: <key>，而不是 Authorization: Bearer。使用 POST /case/{CODE}/bulk 并传入 cases 数组，而不是分别发送 N 个 POST 请求。不要使用 TestRail 的 add_case／custom_steps_separated。

TestRail 的 CSV 导入（将标题行映射到导入字段：Title、Section Hierarchy、Steps (Separated)、Expected Result、Priority、Type、Preconditions）见 references/import-and-traceability.md——必须使用带标题行的真实 CSV，绝不能使用自由格式的散文或单个 Description 列；如果用户要求 CSV，也绝不能使用 JSON。

组织结构

使用章节和子章节构建层级，并保持浅层（3–4 级）。对于 Web + 移动端产品，默认采用单仓库模式，按平台设置顶层章节 （Web、Mobile (iOS)、Mobile (Android)、Shared / API），并在其下设置功能章节。仅当不同平台由不同团队负责且发布节奏不同，才拆分为多个套件。

避免：每个测试用例单独建一个文件夹、嵌套层级过深（7 级以上）、将所有用例都堆在根章节，以及在不同套件中重复相同用例（保留唯一事实来源）。单仓库与多个套件之间的权衡，以及完整的组织规则，请参阅 references/import-and-traceability.md。

---

可追溯性

目标：生成一份覆盖率报告，显示哪些用户故事没有测试——即未覆盖的需求。

对于 Jira 上的 Xray：在每个 Test 中，添加指向需求 Jira issue key 的原生 "tests" issue link（不要指向 Test Execution——它记录的是测试运行，而非覆盖情况）。从 Story 的 Test Coverage 面板查看单个用户故事的覆盖率，从 Traceability Report / Requirement Coverage report 查看项目整体覆盖率。然后筛选出关联测试数为 0 的需求——这些就是需要补齐的缺口。不要只提出用手动电子表格作为唯一的可追溯性机制，也不要忽略未覆盖的需求。Zephyr Scale、Qase 和 TestRail 的对应方式（issue links 及其覆盖率／可追溯性视图）请参阅 references/import-and-traceability.md。

---

自动化晋级

按 ROI 为每个手动用例评分：value ≈ run_frequency × regression_importance ÷ (automation_cost × expected_maintenance)。当产能有限时（例如，Zephyr Scale 中有 400 个待处理用例）：

• **优先自动化：**高频用例（每次发布／回归／冒烟测试都会运行），针对稳定／低变更／确定性功能，并能保护关键回归或冒烟测试路径。
• **继续手动测试：**探索性或一次性用例、很少运行的用例、仍在频繁变动中的 UI、高不稳定性／非确定性行为，以及需要人工判断的用例。

拒绝“全部自动化”和“优先自动化不稳定、频繁变化的 UI”这两种做法——它们都会把稀缺产能用在 ROI 最差的候选项上。完整决策规则请参阅 references/import-and-traceability.md。用例晋级后，实际测试代码应使用 ai-test-generation 或框架技能（playwright-automation、api-testing）编写——而非在此处编写。

---

评审规范

• 每个用例都应能在一个屏幕内完成评审：标题说明结果，前置条件完整，步骤明确，每一步都有可观察的预期结果，测试数据具体。
• 新用例合并前，先运行 lint 检查清单；拒绝非确定性的预期结果。
• 创建用例时就关联需求，不要事后补关联。
• 为套件添加标签（smoke / regression / platform），以便筛选测试运行；没有标签的 400 个用例仓库将无法用于发布筛选。

---

反模式

1. 用一个含糊步骤搭配“验证它能正常工作”作为预期结果

“测试登录 → 验证它能正常工作”无法执行。应编写明确的步骤，为每一步设置一个可观察的预期结果，并明确前置条件、提供具体测试数据。

2. 被要求 lint 套件时敷衍放行

只说步骤“看起来没问题”，或稍作改写却保留“所有功能都正常”和“稍等片刻”等内容，正是 lint 要抓出的问题。标记每个无法验证的预期结果，并将其改写。

3. 混用四种工具的 API

在 Qase 上使用 Bearer（它使用 Token）、在 Qase 或 Zephyr 上使用 add_case/custom_steps_separated、在 Xray Cloud 上使用 /rest/raven/1.0/、在 Zephyr Scale Cloud 上使用 /v1/，以及在 Zephyr 的 create 请求体中将步骤作为文本块传入。这些做法都会导致 4xx 错误或静默写入错误字段。请从对应工具的正确章节复制。

4. 用一个巨型用例覆盖包含多条规则的用户故事

将“有效／已过期／已使用”合并为一个用例，只会得到一个通过／失败结果，掩盖具体是哪条规则出错。每条规则单独编写一个用例。

5. 将 CSV 写成自由格式文本或只有一个 Description 列

没有表头行、且未映射到导入器字段的 TestRail 导入文件需要手动重新映射。请提供 Title、Section Hierarchy、Steps (Separated)、Expected Result 等字段。

6. 深层嵌套和每个用例单独建文件夹

超过 7 层的树状结构，以及每个用例一个文件夹的做法，会让仓库难以浏览。将分区控制在 3–4 层，并保持浅层嵌套；对于 Web + 移动端项目，将平台放在顶层。

7. 用手动维护的电子表格跟踪可追溯性

手动维护的表格无法可靠回答“哪些用户故事没有测试”。请使用工具原生的需求→测试关联和覆盖率/可追溯性报告，并列出未覆盖的需求。

8. 什么都自动化／优先自动化不稳定的内容

优先自动化一次性探索性用例或变化频繁、易出现不稳定问题的 UI，会耗费资源，且投资回报为负。应先按顺序自动化稳定、高频的回归／冒烟测试。

---

验证

交付前，先用最小检查证明生成的产物确实可用：

• 检查自己的输出： 搜索生成的用例中是否包含被禁止的预期结果 — grep -niE "verify it works|looks right|is fine|wait a bit|no problems|everything works" cases.* 必须没有返回结果。任何命中都表示预期结果不确定，需要重写。
• TestRail CSV： 打开文件并确认存在表头行，其中包含 Title、Section Hierarchy、 Steps (Separated)、Expected Result — head -1 cases.csv 应显示这些列，而不是只有一个 Description。试运行导入向导；表头正确时，向导会自动匹配列，无需手动重新映射。
• API 负载，在实际 POST 之前： 验证 JSON（jq . payload.json 退出状态为 0），并 确认身份验证标头和端点与目标工具在工具负载中的条目相符 — Qase 使用 Token:，而非 Authorization: Bearer；TestRail 使用 add_case/{section_id}，而非 add_test。响应中的 201／测试 ID（或 Zephyr 返回 200 且包含新用例的 key）表示创建成功；401 表示身份验证方案接错了，400 表示 步骤字段接错了。
• 可追溯性： 运行工具的覆盖率／可追溯性报告，并确认报告列出了关联测试数为 0 的需求 — 如果“未覆盖”列为空，说明关联已生效；如果列中有内容，那就是需要解决的缺口清单。

---

完成标准

• 每个生成的用例都包含标题、前置条件、独立步骤、每步一个可观察的预期结果，以及具体测试数据 — 预期结果中不能出现“verify it works”／“looks right”／“wait a bit”。
• 一条包含多条规则的用户故事应为每条规则生成一个用例，而不是生成一个合并用例。
• 生成的任何 API 负载都使用正确工具的身份验证方案、端点和步骤字段名称（TestRail 使用 custom_steps_separated+add_case/{section_id}；Xray 使用双步身份验证 + GraphQL createTest，Gherkin 使用 Cucumber；Zephyr 使用 /v2 Bearer + 单独的 /teststeps；Qase 使用 Token 标头 + /case/{CODE}/bulk）。
• 任何 TestRail CSV 都有表头行，可将列映射到导入器字段（Title、 Section Hierarchy、Steps (Separated)、Expected Result）。
• 检查过的测试套件会标记并改写所有含糊步骤 — 如果存在问题，不得声称“未发现问题”。
• 可追溯性使用工具原生的需求→测试关联，并通过覆盖率报告列出未覆盖的需求。
• 自动化升级流程会生成按投资回报排序的列表（先处理稳定、高频的回归／冒烟测试），并说明哪些内容仍保留为手动测试。

---

相关技能

• ai-test-generation — 前往此处，将已升级的手动用例转为自动化测试代码；此技能仅处理手动／混合用例及其导入负载。
• test-planning — 前往此处，为冲刺／发布选择要测试的内容；此技能会在范围确定后编写用例。
• exploratory-testing — 一次性／基于测试章程的用例来源，这些用例应保留为手动测试；可与此处的自动化升级决策配合使用。
• qa-project-context — 通用依赖项：此技能在生成任何负载前读取的工具、项目键和约定。

---

参考文件（位于 references/ 中）

• tool-apis.md — TestRail / Xray Cloud / Zephyr Scale / Qase 的完整创建用例请求负载 （curl + GraphQL）、认证流程，以及各工具之间的交叉配置陷阱。
• linting.md — 步骤歧义检查清单、四个经典错误步骤的改写示例，以及检查输出表格格式。
• import-and-traceability.md — TestRail CSV 列到字段的映射及 3 个用例示例、测试套件/分区组织规则、需求可追溯性 + 覆盖缺口报告，以及自动化升级决策规则。