编写可复现的手工测试用例并导入…

当你需要从用户故事或验收标准编写、审查、批量导入手工/混合测试用例，或做需求覆盖率与自动化升级决策时使用。

适用场景

解决思路

1. 先检查项目根目录的 `.agents/qa-project-context.md` 获取工具、项目 key 和约定，已答内容跳过；若缺失建议用 `qa-project-context` 技能创建。
2. 确认目标工具是 TestRail、Xray、Zephyr Scale 还是 Qase，因为四者认证方式、端点结构和步骤字段名各不相同，弄错会导致 401 或 400。
3. TestRail 需确认是单仓库模式还是多套件模式，这决定用例放在一个套件的 section 下还是独立套件中，影响每个 `section_id` 和组织方案。
4. Xray/Zephyr 需确认是 Jira Cloud 还是 Server/DC，Cloud 与 Server 的 base path 和认证不同（本技能针对 Cloud）。
5. 确认用例来源是验收标准、用户故事还是自由描述，以决定生成多少用例以及如何拆分规则。
6. 若需要需求追溯，现在就记录 Jira/需求 issue key，让用例创建时即建立链接而非事后补填。
7. 每个用例必须包含五部分：标题（功能—场景—预期结果，一行）、前置条件（账号存在、在 X 页面、开关已开）、步骤（每步一个动作）、预期结果（每步一个可观察后置条件）、测试数据（具体验证码、邮箱、次数、时间）。
8. 预期结果必须可确定性判定：给出精确值、具名元素及其状态、具体消息、状态码、数量或有时间边界的条件；禁止“能工作”“看起来对”“没问题”“等一会儿”。
9. 每个步骤只放一个断言，一个预期结果；把三个检查塞进一步会让失败原因和重跑范围变得模糊。
10. 每条业务规则一个用例，不要一个巨型用例：如“有效码减总额 / 过期码报错 / 已用码被拒”应拆成三个独立通过/失败判定的用例。
11. 从故事批量编写时按规则拆分：折扣码故事生成三个用例（有效码减总额、过期码内联报错且总额不变、已用码被拒且总额不变），团队需要边界覆盖时补充空码、格式错误码等隐含负例。
12. 审查步骤时主动标记非确定性步骤并重写，不要附和“看起来没问题”；标记模糊动作（“点一点”“测试 X”）、模糊数据（“一些数据”）、不可观察预期（“一切正常”）、无界等待（“等一会儿”）、一步多断言。
13. 重写经典四步坏套件（“应用打开 / 一切正常 / 看起来对 / 报告就绪”）时，为每步补上明确选择器、精确值和有界条件，绝不返回“未发现问题”。
14. 生成 API 载荷时严格按工具区分：TestRail 用 Basic `email:api_key`，`POST add_case/{section_id}`，步骤字段为 `custom_steps_separated` 数组 `{content, expected}`，base 为 `{instance}/index.php?/api/v2`，不要用 `add_test` 或 Qase 式 `POST /case`。
15. Xray Cloud 先 `POST /api/v2/authenticate`（client_id/client_secret）拿 Bearer token（24 小时），再用 GraphQL `createTest` 于 `/api/v2/graphql`，步骤为 `steps[] {action, result}`；Gherkin 用 `testType: Cucumber` + `gherkin`，避免已废弃的 `/rest/raven/1.0/...` 和 Server 式 REST 及 Jira 用户名密码 Basic 认证。
16. Zephyr Scale Cloud 用 `Authorization: Bearer <JWT>`，base 为 `api.zephyrscale.smartbear.com/v2`，先 `POST /v2/testcases` 再单独 `POST /v2/testcases/{key}/teststeps`，步骤为 `inline {description, expectedResult, testData}`，不要用 `/v1/`、错误主机或 Qase 的 `Token` 头。
17. Qase 用 header `Token: <key>`（不是 `Authorization: Bearer`），用 `POST /v1/case/{CODE}/bulk` 带 `cases` 数组而非 N 次单条 POST，步骤为 `steps[] {action, expected_result, data}`，不要用 TestRail 的 `add_case`/`custom_steps_separated`。
18. TestRail CSV 导入必须用带表头的真实 CSV，列映射到导入器字段：`Title`、`Section Hierarchy`、`Steps (Separated)`、`Expected Result`、`Priority`、`Type`、`Preconditions`；不要用自由文本、单一 Description 列，或在要求 CSV 时给 JSON。
19. 组织用例用 section 和子 section 保持浅层（3–4 层）；Web+移动产品默认单仓库模式，顶层按平台分（`Web`、`Mobile (iOS)`、`Mobile (Android)`、`Shared / API`），其下按功能分；仅当平台由不同团队以不同节奏负责时才拆多套件。
20. 避免每个用例一个文件夹、7 层以上深嵌套、全部堆在根 section、跨套件重复同一用例（保持单一事实来源）。
21. 追溯目标：产出显示哪些故事没有测试的覆盖率报告；Xray on Jira 从每个 Test 添加原生 “tests” issue link 到需求 Jira issue key（不要链到 Test Execution），从 Story 的 Test Coverage 面板读单故事覆盖，从 Traceability Report / Requirement Coverage report 读项目级覆盖，再筛选 0 链接测试的需求作为待补缺口。
22. 自动化升级按 ROI 评分：`value ≈ run_frequency × regression_importance ÷ (automation_cost × expected_maintenance)`；优先自动化高频（每发布/回归/冒烟都跑）、稳定低变更确定性功能、守护关键回归或冒烟路径的用例。
23. 保持手工：探索性或一次性用例、极少运行的用例、仍在变动的高变更 UI、不稳定/非确定性行为、需要人工判断的用例；拒绝“全部自动化”和“先自动化易变 UI”。
24. 审查卫生：每个用例一屏可审（标题说明结果、前置条件齐全、步骤离散、每步预期可观察、测试数据具体）；新用例合并前跑 lint 清单，拒绝非确定性预期；创建时即链接需求；给套件打标签（smoke/regression/platform）以便运行筛选。
25. 交付前自检：用 `grep -niE "verify it works|looks right|is fine|wait a bit|no problems|everything works" cases.*` 检查生成用例，必须无命中。
26. TestRail CSV 用 `head -1 cases.csv` 确认表头含 `Title`、`Section Hierarchy`、`Steps (Separated)`、`Expected Result`，并试跑导入向导确认自动匹配列无需手工重映射。
27. API 载荷真实 POST 前：`jq . payload.json` 退出码为 0，并核对认证头和端点与目标工具一致（Qase 用 `Token:` 而非 `Authorization: Bearer`，TestRail 用 `add_case/{section_id}` 而非 `add_test`）；响应 `201`/test-id（Zephyr 为 `200` 带新 case `key`）确认创建成功，`401` 说明认证方式串线，`400` 说明步骤字段错误。
28. 追溯验证：运行工具的 coverage/Traceability 报告，确认列出 0 链接测试的需求；“未覆盖”列为空说明链接已落地，有内容即为待补缺口清单。

适用边界 · 注意事项

• 不用于生成自动化测试代码——那属于 ai-test-generation。
• 不用于冲刺级别的“测什么”范围选择——那属于 test-planning。
• 不适用于 Xray/Zephyr 的 Jira Server/DC 环境，本技能针对 Cloud，Server 使用不同端点。