Back to Details

test-case-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<objective> A manual test case that says "test the login" with expected result "verify it works" passes every review and catches nothing — two testers run it differently and neither can say whether it failed. This skill produces deterministic cases (discrete steps, one observable expected result each, concrete test data), organizes them into navigable suites, and emits the tool-correct API/CSV payloads for TestRail, Xray Cloud, Zephyr Scale, and Qase — whose look-alike APIs use different auth schemes, endpoints, and step-field names that agents routinely cross-wire. </objective>
<objective> 一个仅写着“测试登录”且预期结果为“验证功能正常”的手动测试用例，能通过所有评审但毫无检测价值——两名测试人员执行时的操作会不一致，且无法判断测试是否失败。本技能可生成确定性测试用例（步骤离散、每个步骤对应一个可观测的预期结果、使用具体测试数据），将其组织为便于导航的测试套件，并输出TestRail、Xray Cloud、Zephyr Scale和Qase所需的正确API/CSV负载——这些工具的API看似相似，但使用不同的认证方案、端点和步骤字段名，容易被混淆使用。 </objective>

Quick Route

快速导航

RequestGo to
Write one well-formed case from an ACTest-Case Anatomy
Bulk-generate cases from a storyBulk Authoring + tool section
"Lint these steps / are these verifiable?"Ambiguous-Step Linting + 
references/linting.md
TestRail / Xray / Zephyr / Qase API payloadTool Payloads + 
references/tool-apis.md
CSV to import into TestRail
references/import-and-traceability.md
(CSV section)
Organize suites/sections
references/import-and-traceability.md
(organization)
Requirements ↔ tests, coverage gapsTraceability + 
references/import-and-traceability.md
Manual → automation decisionAutomation Graduation
请求跳转至
基于验收标准编写一个规范的测试用例测试用例结构
基于用户故事批量生成测试用例批量编写测试用例 + 对应工具章节
“检查这些步骤的规范性 / 这些步骤是否可验证？”模糊步骤检查 + 
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
手动测试转自动化的决策自动化转化

Discovery Questions

前置确认问题

First, check 
.agents/qa-project-context.md
in the project root for the tool, project keys, and conventions; skip anything answered there. If it's missing, suggest creating one with the 
qa-project-context
skill. Then clarify:
  • Which tool — TestRail, Xray, Zephyr Scale, or Qase? Each has a different API auth scheme, endpoint shape, and step-field name. Getting this wrong produces payloads that 401 or 400.
  • TestRail only: single-repository mode or multiple suites? Changes whether cases live under sections in one suite or in separate suites — affects every 
    section_id
    and the org plan.
  • Xray/Zephyr only: Jira Cloud or Server/DC? Cloud and Server use different base paths and auth. This skill targets Cloud; Server uses different endpoints.
  • Source of the cases — acceptance criteria, a user story, a free-form feature? Drives how many cases to generate and how to split rules.
  • Do you need requirement traceability? If yes, capture the Jira/requirement issue keys now so cases link on creation rather than being back-filled.
首先，查看项目根目录下的
.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/需求的问题密钥，以便在创建测试用例时直接关联，避免后续补录。

Core Principles

核心原则

  1. An expected result must be deterministically checkable. A second human (or a machine) must be able to agree on pass/fail without guessing. "Works", "looks right", "is fine", "wait a bit" fail this test. Name an exact value, a named element and its state, a specific message, a status code, a count, or a time-bounded condition.
  2. One assertion per step. Each step has a single expected result. Cramming three checks into one step makes a failure ambiguous about which check broke and which to re-run.
  3. One case per business rule, not one giant case. "Valid code reduces total / expired code errors / used code rejected" is three cases with three independent pass/fail verdicts — not one case with a paragraph of expecteds.
  4. The tool's API is the spec — don't cross-wire the four tools. TestRail's 
    custom_steps_separated
    , Qase's 
    Token
    header, Xray's two-step GraphQL auth, and Zephyr's separate 
    teststeps
    call are NOT interchangeable. Copy from the right tool's section.
  5. Traceability exists to surface what is NOT covered. The deliverable is the list of requirements with zero linked tests, from a native coverage report — not a spreadsheet that rots and not "every test links to something."
  6. Automate by ROI, not by volume. Limited capacity means stable, high-frequency, regression/smoke cases graduate first; exploratory, one-off, and high-churn/flaky cases stay manual. "Automate everything" wastes capacity on the worst candidates.
  1. 预期结果必须可确定性验证。另一个人（或机器）必须能明确判断测试通过或失败，无需猜测。“功能正常”、“显示正确”、“没问题”、“稍等片刻”这类描述不符合要求。应指定精确值、命名元素及其状态、特定提示信息、状态码、数量或有时间限制的条件。
  2. 每个步骤对应一个断言。每个步骤仅包含一个预期结果。将多个检查点塞进一个步骤会导致失败时无法明确是哪个检查点出问题，也不利于重测。
  3. 每条业务规则对应一个测试用例，而非一个巨型用例。“有效码减免总额/过期码报错/已使用码被拒绝”对应三个独立的测试用例，每个用例有独立的通过/失败判定——不应合并为一个包含多段预期结果的巨型用例。
  4. 工具API是唯一标准——不要混淆四款工具的配置。TestRail的
    custom_steps_separated
    、Qase的
    Token
    请求头、Xray的两步GraphQL认证、Zephyr的独立
    teststeps
    调用不可互换。请严格复制对应工具章节的配置。
  5. 可追溯性的目的是暴露未覆盖的需求。交付物应为原生覆盖报告中显示的“未关联任何测试用例的需求列表”——而非易失效的电子表格，也不是“每个测试用例都关联了某个需求”的形式。
  6. 基于ROI（投资回报率）选择自动化对象，而非数量。资源有限时，应优先将稳定、高频执行的回归/冒烟测试用例转为自动化；探索性、一次性、高变动/不稳定的测试用例应保持手动。“自动化所有内容”会浪费资源在ROI最低的候选对象上。

Test-Case Anatomy

测试用例结构（Test-Case Anatomy）

A well-formed manual case has five parts. Every part is mandatory; a case missing preconditions or test data is not reproducible.
PartWhat it holdsFailure if omitted
TitleFeature — scenario — expected outcome, one lineUnsearchable, duplicated
PreconditionsState the test assumes (account exists, on page X, flag on)Tester guesses setup; flaky
StepsDiscrete actions, one action per stepNon-reproducible
Expected ResultsOne observable post-condition per stepNot verifiable
Test DataConcrete values used (codes, emails, counts, timings)Not repeatable
BAD (single vague step, non-verifiable expected, no preconditions, no data):
Title: Login test
Steps: Test the login.
Expected: Verify it works.
GOOD — from the AC "after 5 wrong-password attempts, the account locks for 15 minutes":
Title: Login — account locks for 15 minutes after 5 failed attempts
Preconditions: A registered account exists for user@example.com. The user is logged out
               on the /login page. Lockout policy: 5 attempts, 15-minute lockout.
Test Data: email user@example.com, wrong password "WrongPass!", correct password "Passw0rd!"
Steps (one assertion per step / single expected result each):
  1. Action:   Submit the login form with user@example.com 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.
Note: explicit preconditions, concrete test data (5 attempts, 15-minute lockout), discrete steps, and a single deterministic expected result per step.
一个规范的手动测试用例包含五个部分，缺一不可；缺少前置条件或测试数据的用例无法复现。
组成部分包含内容缺失后的问题
Title功能——场景——预期结果，单行描述无法搜索、易重复
Preconditions测试预设的状态（如账户已存在、处于X页面、功能开关已开启）测试人员需自行猜测前置配置，导致测试结果不稳定
Steps离散的操作步骤，每个步骤对应一个操作无法复现测试过程
Expected Results每个步骤对应一个可观测的后置状态无法验证测试结果
Test Data测试使用的具体值（如验证码、邮箱、数量、时长）测试结果无法重复
反面示例（步骤模糊、预期结果不可验证、无前置条件、无测试数据）：
Title: 登录测试
Steps: 测试登录功能。
Expected: 验证功能正常。
正面示例——基于验收标准“连续5次密码错误后，账户锁定15分钟”：
Title: 登录——连续5次密码错误后账户锁定15分钟
Preconditions: 存在已注册账户user@example.com，用户已在/login页面登出。锁定策略：5次错误尝试后锁定15分钟。
Test Data: 邮箱user@example.com，错误密码"WrongPass!"，正确密码"Passw0rd!"
Steps (one assertion per step / single expected result each):
  1. Action:   使用user@example.com和"WrongPass!"提交登录表单。
     Expected: 显示错误提示"Invalid email or password."，失败尝试次数变为1。
  2. Action:   重复提交错误密码，直到累计5次失败尝试。
     Expected: 第5次失败后账户被锁定，显示提示"Account locked. Try again in 15 minutes."
  3. Action:   立即使用正确密码"Passw0rd!"提交登录。
     Expected: 登录仍被阻止，显示相同的锁定提示（锁定优先级高于有效凭证）。
  4. Action:   等待15分钟后，使用正确密码提交登录。
     Expected: 登录成功，仪表盘加载完成。
注：包含明确的前置条件、具体的测试数据（5次尝试、15分钟锁定）、离散的步骤，且每个步骤对应一个确定性的预期结果。

Bulk Authoring from Stories

基于用户故事批量编写测试用例（Bulk Authoring from Stories）

Given a story or set of acceptance criteria, split into cases by rule, then generate the tool-specific payload. Worked example for the discount-code story (valid reduces total / expired errors / already-used rejected) → three cases:
  1. Apply a valid code → total reduces (happy path).
  2. Apply an expired (invalid) code → inline error, total unchanged.
  3. Apply an already-used / already-redeemed code → rejected, total unchanged.
Add the obvious negatives the story implies but doesn't state (empty code, malformed code) when the team wants edge coverage. Each case gets discrete steps and one expected per step — never one giant case covering all three rules. For the WHAT-to-test scope decision across a sprint, that's 
test-planning
, not this skill.
给定用户故事或一组验收标准，按照业务规则拆分测试用例，然后生成对应工具的负载。以折扣码故事为例（有效码减免总额/过期码报错/已使用码被拒绝）→ 三个测试用例：
  1. 使用有效折扣码 → 总额减免（正常流程）。
  2. 使用过期（无效）折扣码 → 显示内联错误，总额不变。
  3. 使用已使用/已兑换的折扣码 → 被拒绝，总额不变。
当团队需要覆盖边缘场景时，补充用户故事隐含但未明确提及的负面场景（如空码、格式错误的码）。每个测试用例需包含离散步骤和单个预期结果——绝不能合并为一个覆盖所有规则的巨型用例。关于迭代级测试范围的选择，请使用
test-planning
技能，而非本技能。

Ambiguous-Step Linting

模糊步骤检查（Ambiguous-Step Linting）

When asked to "lint" a suite, your job is to FLAG non-deterministic steps and rewrite them — NOT to agree that they "look fine." The agreeable failure mode (rubber-stamping "everything works") is the exact thing this section prevents.
A step is bad when its expected result is not deterministically verifiable. Flag any of:
  • Vague action — "click around", "test the X", "play with it" → name the exact element + action.
  • Vague data — "some data", "a value", "stuff" → give concrete test data.
  • Non-observable expected — "everything works", "it looks right", "is fine", "no problems" → name the exact observable result.
  • Unbounded wait — "wait a bit", "after a while" → bound it ("within 10 s" / "until the spinner disappears and a row appears").
  • Multiple assertions in one step → split to one assertion per step.
For the classic four-step bad suite ("app opens / everything works / it looks right / the report is ready"), all four are ambiguous and must be flagged and rewritten with explicit selectors, exact values, and bounded conditions — never returned as "no issues found". The full lint checklist, the worked rewrite of those four steps, and the lint-output table format are in 
references/linting.md
.
当被要求“检查”测试套件时，你的任务是标记非确定性步骤并重新编写——而非默认“看起来没问题”。这种敷衍的处理方式正是本章节要避免的。
当步骤的预期结果无法被确定性验证时，该步骤即为不合格。需标记以下情况：
  • 模糊操作——“点击各处”、“测试X功能”、“随意操作” → 需明确指定操作的元素和动作。
  • 模糊数据——“一些数据”、“某个值”、“相关内容” → 需提供具体的测试数据。
  • 不可观测的预期结果——“一切正常”、“显示正确”、“没问题”、“无异常” → 需明确指定可观测的结果。
  • 无时间限制的等待——“稍等片刻”、“过一会儿” → 需添加时间限制（如“10秒内” / “直到加载 spinner 消失并显示行数据”）。
  • 单个步骤包含多个断言 → 拆分为每个步骤对应一个断言。
对于经典的四步不合格套件（“应用启动/一切正常/显示正确/报告准备就绪”），四个步骤均存在模糊性，必须标记并重新编写，明确选择器、精确值和有界条件——绝不能返回“未发现问题”。完整的检查清单、这四个步骤的重写示例以及检查结果的表格格式，请参考
references/linting.md
。

Tool Payloads

工具负载（Tool Payloads）

The four tools are easy to cross-wire. Summary — full curl/GraphQL bodies in 
references/tool-apis.md
:
ToolAuthCreate endpointSteps field
TestRailBasic 
email:api_key
POST add_case/{section_id}
custom_steps_separated
array of 
{content, expected}
Xray Cloud
POST /api/v2/authenticate
→ Bearer token		GraphQL 
createTest
at 
/api/v2/graphql
steps[] {action, result}
; Gherkin → 
testType: Cucumber
+ 
gherkin
Zephyr Scale Cloud
Authorization: Bearer <JWT>
POST /v2/testcases
then 
POST /v2/testcases/{key}/teststeps
separate 
teststeps
call, 
inline {description, expectedResult, testData}
Qaseheader 
Token: <key>
POST /v1/case/{CODE}/bulk
steps[] {action, expected_result, data}
Tool-specific traps that the reference spells out and you must respect:
  • TestRail — separated steps need 
    custom_steps_separated
    (NOT the plain 
    custom_steps
    text blob); the endpoint is 
    add_case/{section_id}
    (NOT 
    add_test
    , which is a run instance). Base is 
    {instance}/index.php?/api/v2
    . Don't use a Qase-style 
    POST /case
    .
  • Xray Cloud — authenticate first (
    /api/v2/authenticate
    with client_id/client_secret → bearer, 24h), then prefer GraphQL 
    createTest
    . Import Gherkin as a Cucumber test, not a Generic one. Avoid the deprecated Cloud path 
    /rest/raven/1.0/...
    and Server-style REST and Jira username/password basic auth.
  • Zephyr Scale Cloud — base is 
    api.zephyrscale.smartbear.com/v2
    with JWT Bearer. Steps are a SEPARATE 
    /testcases/{key}/teststeps
    call, not a text blob in the create body. Don't emit 
    /v1/
    , the wrong host, or Qase's 
    Token
    header.
  • Qase — auth is 
    Token: <key>
    , NOT 
    Authorization: Bearer
    . Use 
    POST /case/{CODE}/bulk
    with a 
    cases
    array instead of N single POSTs. Don't use TestRail's 
    add_case
    / 
    custom_steps_separated
    .
CSV import for TestRail (header row mapped to importer fields: 
Title
, 
Section Hierarchy
, 
Steps (Separated)
, 
Expected Result
, 
Priority
, 
Type
, 
Preconditions
) is in 
references/import-and-traceability.md
— use a real CSV with a header row, never free-form prose or a single Description column, and never JSON when CSV was requested.
四款工具的配置容易混淆。以下是摘要——完整的curl/GraphQL请求体请参考
references/tool-apis.md
：
ToolAuthCreate endpointSteps field
TestRailBasic 
email:api_key
POST add_case/{section_id}
custom_steps_separated
数组，元素格式为
{content, expected}
Xray Cloud
POST /api/v2/authenticate
→ Bearer token		GraphQL 
createTest
，端点为
/api/v2/graphql
steps[] {action, result}
；Gherkin格式需设置
testType: Cucumber
+ 
gherkin
字段
Zephyr Scale Cloud
Authorization: Bearer <JWT>
先
POST /v2/testcases
，再
POST /v2/testcases/{key}/teststeps
需单独调用
teststeps
接口，格式为
inline {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
    获取Bearer token，有效期24小时），然后优先使用GraphQL的
    createTest
    接口。导入Gherkin格式时需设置为Cucumber测试类型，而非通用类型。避免使用已废弃的Cloud路径
    /rest/raven/1.0/...
    以及Server版本的REST接口和Jira用户名/密码基础认证。
  • 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
    数组，而非多次调用单个创建接口。请勿使用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。

Organization

测试套件组织（Organization）

Use sections and subsections for hierarchy, kept shallow (3–4 levels). For a web + mobile product the default is single-repository mode with top-level sections per platform (
Web
, 
Mobile (iOS)
, 
Mobile (Android)
, 
Shared / API
), feature sections beneath. Split into multiple suites only when platforms are owned by separate teams with separate cadences.
Avoid: one folder per test case, deep nesting 7+ levels deep, dumping every case in the root section, and duplicating the same case across suites (keep one source of truth). The single-repository vs multiple-suites trade-off and the full org rules are in 
references/import-and-traceability.md
.
使用章节和子章节构建层级结构，保持层级较浅（3-4层）。对于Web+移动产品，默认采用单仓库模式，顶层章节按平台划分（
Web
、
Mobile (iOS)
、
Mobile (Android)
、
Shared / API
），下方再按功能划分章节。仅当各平台由独立团队维护且迭代节奏不同时，才拆分为多个套件。
避免：每个测试用例对应一个文件夹、层级嵌套超过7层、所有测试用例都放在根章节、同一测试用例重复出现在多个套件中（保持单一数据源）。单仓库模式与多套件模式的权衡以及完整的组织规则，请参考
references/import-and-traceability.md
。

Traceability

需求可追溯性（Traceability）

Goal: a coverage report that shows which stories have no tests — the uncovered requirements.
For Xray on Jira: from each Test, add the native "tests" issue link to the requirement's Jira issue key (NOT to a Test Execution — that records runs, not coverage). Read per-story coverage from the Story's Test Coverage panel, and project-wide from the Traceability Report / Requirement Coverage report. Then filter for requirements with 0 linked tests — those are the gaps to close. Do not propose a manual spreadsheet as the only traceability mechanism, and do not ignore uncovered requirements. Zephyr Scale, Qase, and TestRail equivalents (issue links + their coverage/traceability views) are in 
references/import-and-traceability.md
.
目标：生成覆盖报告，明确哪些用户故事未关联测试用例——即未覆盖的需求。
对于Jira上的Xray：在每个测试用例中添加原生的**“tests”问题链接**，关联到需求的Jira问题密钥（而非关联到Test Execution，后者记录的是测试运行情况，而非覆盖情况）。从用户故事的Test Coverage面板查看单故事的覆盖情况，从Traceability Report / Requirement Coverage report查看项目级覆盖情况。然后筛选出关联测试用例数为0的需求——这些就是需要填补的覆盖缺口。请勿仅使用手动电子表格作为可追溯性机制，也不要忽略未覆盖的需求。Zephyr Scale、Qase和TestRail的等效配置（问题链接+覆盖/可追溯性视图）请参考
references/import-and-traceability.md
。

Automation Graduation

自动化转化（Automation Graduation）

Score each manual case by ROI: 
value ≈ run_frequency × regression_importance ÷ (automation_cost × expected_maintenance)
. With limited capacity (e.g. a 400-case Zephyr Scale backlog):
  • Automate first: high-frequency cases (run every release / regression / smoke), on stable / low-churn / deterministic features, that guard critical regression or smoke paths.
  • Stay manual: exploratory or one-off cases, rarely-run cases, high-churn UI still in flux, flaky / non-deterministic behavior, and cases needing human judgment.
Reject "automate everything" and "automate the flaky, frequently changing UI first" — both spend scarce capacity on the worst-ROI candidates. Full decision rule in 
references/import-and-traceability.md
. Once a case graduates, the actual test code is written with 
ai-test-generation
or a framework skill (
playwright-automation
, 
api-testing
) — not here.
通过ROI评分判断每个手动测试用例是否适合自动化：
价值 ≈ 执行频率 × 回归重要性 ÷ (自动化成本 × 预期维护成本)
。当资源有限时（例如Zephyr Scale中有400个测试用例）：
  • 优先自动化：高频执行的测试用例（每次发布/回归/冒烟测试都需执行）、针对稳定/低变动/确定性功能的测试用例、守护关键回归或冒烟测试路径的用例。
  • 保持手动：探索性或一次性测试用例、极少执行的用例、仍在频繁变动的高 churn UI、不稳定/非确定性的行为、需要人工判断的测试用例。
拒绝“自动化所有内容”和“优先自动化不稳定、频繁变动的UI”——这两种方式都会将稀缺资源浪费在ROI最低的候选对象上。完整的决策规则请参考
references/import-and-traceability.md
。一旦测试用例转为自动化，实际的测试代码需使用
ai-test-generation
或框架技能（
playwright-automation
、
api-testing
）编写——本技能不负责此环节。

Review Hygiene

评审规范（Review Hygiene）

  • Every case is reviewable in one screen: title states the outcome, preconditions present, steps discrete, each expected observable, test data concrete.
  • Run the lint checklist on a new case before it merges; reject non-deterministic expecteds.
  • Link to the requirement at creation time, not as a back-fill.
  • Tag the suite (smoke / regression / platform) so runs can filter; an untagged 400-case repo is unusable for release selection.
  • 每个测试用例可在一个屏幕内完成评审：标题明确预期结果、包含前置条件、步骤离散、每个预期结果可观测、测试数据具体。
  • 新测试用例合并前需执行检查清单，拒绝非确定性的预期结果。
  • 创建测试用例时即关联需求，而非后续补录。
  • 为测试套件添加标签（冒烟/回归/平台），以便在执行测试时筛选；未添加标签的400个测试用例的仓库无法用于发布选择。

Anti-Patterns

反模式（Anti-Patterns）

1. One vague step with a "verify it works" expected

1. 单个模糊步骤搭配“验证功能正常”的预期结果

"Test the login → verify it works" is unrunnable. Write discrete steps, one observable expected each, explicit preconditions, concrete test data.
“测试登录 → 验证功能正常”的测试用例无法执行。需编写离散步骤、每个步骤对应一个可观测的预期结果、明确前置条件、使用具体测试数据。

2. Rubber-stamping a suite when asked to lint it

2. 检查测试套件时敷衍了事

Saying steps "look fine" or lightly rewording while leaving "everything works" and "wait a bit" in place is the failure linting exists to catch. Flag every non-verifiable expected and rewrite it.
当被要求检查时，仅说步骤“看起来没问题”或轻微修改但保留“一切正常”、“稍等片刻”等描述，这正是检查机制要避免的失败情况。需标记所有不可验证的预期结果并重新编写。

3. Cross-wiring the four tools' APIs

3. 混淆四款工具的API配置

Bearer on Qase (it uses 
Token
), 
add_case
/
custom_steps_separated
on Qase or Zephyr, 
/rest/raven/1.0/
on Xray Cloud, 
/v1/
on Zephyr Scale Cloud, steps as a text blob in Zephyr's create body. Each is a 4xx or a silent wrong-field. Copy from the correct tool section.
在Qase中使用Bearer认证（Qase实际使用
Token
）、在Qase或Zephyr中使用
add_case
/
custom_steps_separated
、在Xray Cloud中使用
/rest/raven/1.0/
路径、在Zephyr Scale Cloud中使用
/v1/
路径、在Zephyr的创建请求体中以文本格式添加步骤。这些错误都会导致4xx错误或字段静默失效。请严格复制对应工具章节的配置。

4. One giant case for a multi-rule story

4. 将多规则用户故事合并为一个巨型测试用例

Folding "valid / expired / already-used" into one case yields a single pass/fail that hides which rule broke. One case per rule.
将“有效/过期/已使用”规则合并为一个测试用例会导致单一的通过/失败结果，无法明确哪条规则失效。每条规则对应一个测试用例。

5. CSV as free-form prose or a single Description column

5. CSV使用自由格式文本或单一Description列

A TestRail import without a header row mapped to importer fields needs manual remapping. Provide 
Title
, 
Section Hierarchy
, 
Steps (Separated)
, 
Expected Result
, etc.
TestRail导入时，如果CSV没有表头与导入工具字段映射，需要手动映射。需提供
Title
、
Section Hierarchy
、
Steps (Separated)
、
Expected Result
等列。

6. Deep nesting and per-case folders

6. 层级嵌套过深且每个测试用例对应一个文件夹

7+ level trees and one-folder-per-case make the repository unnavigable. Keep 3–4 shallow levels of sections; platform at the top for web+mobile.
超过7层的目录结构和每个测试用例对应一个文件夹会导致仓库难以导航。保持3-4层的浅层级结构；对于Web+移动产品，顶层按平台划分。

7. Traceability as a manual spreadsheet

7. 使用手动电子表格实现可追溯性

A hand-kept sheet can't reliably answer "which stories have no tests." Use the tool's native requirement→test link and coverage/Traceability report, and surface the uncovered requirements.
手动维护的表格无法可靠回答“哪些用户故事未关联测试用例”。需使用工具原生的需求→测试用例链接和覆盖/可追溯性报告，并暴露未覆盖的需求。

8. Automate-everything / automate-the-flaky-first

8. 自动化所有内容 / 优先自动化不稳定的用例

Automating one-off exploratory cases or high-churn/flaky UI first burns capacity for negative ROI. Sequence stable high-frequency regression/smoke first.
优先自动化探索性一次性用例或高变动/不稳定的UI会浪费资源，产生负ROI。应优先自动化稳定、高频执行的回归/冒烟测试用例。

Verification

验证方法（Verification）

Prove the produced artifact actually works before handing it off, smallest check first:
  • Lint your own output: grep the generated cases for the banned expecteds — 
    grep -niE "verify it works|looks right|is fine|wait a bit|no problems|everything works" cases.*
    must return nothing. Any hit is a non-deterministic expected to rewrite.
  • TestRail CSV: open it and confirm a header row exists with 
    Title
    , 
    Section Hierarchy
    , 
    Steps (Separated)
    , 
    Expected Result
    — 
    head -1 cases.csv
    should show those columns, not a single 
    Description
    . Dry-run the import wizard; the wizard auto-matches columns with no manual remapping when the headers are right.
  • API payload, before the real POST: validate the JSON (
    jq . payload.json
    exits 0) and confirm the auth header and endpoint match the target tool's row in Tool Payloads — Qase 
    Token:
    not 
    Authorization: Bearer
    , TestRail 
    add_case/{section_id}
    not 
    add_test
    . A 
    201
    /test-id in the response (or a 
    200
    with the new case 
    key
    for Zephyr) confirms the create; a 
    401
    means the auth scheme is cross-wired, a 
    400
    means the step field is.
  • Traceability: run the tool's coverage/Traceability report and confirm it lists requirements with 0 linked tests — an empty "uncovered" column means the links landed; a populated one is the gap list to close.
交付成果前需验证其有效性，从最小检查项开始：
  • 检查自身输出的规范性：在生成的测试用例中搜索禁用的预期结果描述——执行
    grep -niE "verify it works|looks right|is fine|wait a bit|no problems|everything works" cases.*
    应无结果。任何匹配项都需重新编写为确定性预期结果。
  • TestRail CSV验证：打开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的需求——“未覆盖”列空表示链接已正确添加；非空则为需要填补的缺口列表。

Done When

完成标准（Done When）

  • Each generated case has a title, preconditions, discrete steps, one observable expected result per step, and concrete test data — no "verify it works" / "looks right" / "wait a bit" expecteds.
  • A multi-rule story produced one case per rule, not one combined case.
  • Any emitted API payload uses the correct tool's auth scheme, endpoint, and step-field name (TestRail 
    custom_steps_separated
    +
    add_case/{section_id}
    ; Xray two-step auth + GraphQL 
    createTest
    , Cucumber for Gherkin; Zephyr 
    /v2
    Bearer + separate 
    /teststeps
    ; Qase 
    Token
    header + 
    /case/{CODE}/bulk
    ).
  • Any TestRail CSV has a header row mapping columns to importer fields (
    Title
    , 
    Section Hierarchy
    , 
    Steps (Separated)
    , 
    Expected Result
    ).
  • A linted suite returns every ambiguous step flagged and rewritten — never "no issues found" when smells are present.
  • Traceability uses the tool's native requirement→test link and a coverage report that lists the uncovered requirements.
  • Automation graduation produces an ROI-ordered list (stable + high-frequency + regression/smoke first) and names what stays manual.
  • 每个生成的测试用例包含标题、前置条件、离散步骤、每个步骤对应一个可观测的预期结果、具体测试数据——无“验证功能正常”/“显示正确”/“稍等片刻”这类预期结果。
  • 多规则用户故事生成了每个规则对应一个测试用例，而非合并为一个用例。
  • 输出的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
    ）。
  • 检查后的测试套件中所有模糊步骤都被标记并重新编写——当存在问题时绝不能返回“未发现问题”。
  • 可追溯性使用了工具原生的需求→测试用例链接，且覆盖报告列出了未覆盖的需求。
  • 自动化转化输出了按ROI排序的列表（优先稳定+高频+回归/冒烟测试用例），并明确了保持手动的用例。

Related Skills

相关技能（Related Skills）

  • ai-test-generation — go there to turn a graduated manual case into automated TEST CODE; this skill stops at the manual/hybrid case and its import payload.
  • test-planning — go there for sprint/release WHAT-to-test selection; this skill authors the cases once the scope is decided.
  • exploratory-testing — the source of one-off/charter-based cases that should stay manual; pairs with the automation-graduation decision here.
  • qa-project-context — the universal dependency: the tool, project keys, and conventions this skill reads before generating any payload.
  • ai-test-generation——将已转为自动化的手动测试用例生成自动化测试代码时使用；本技能仅负责手动/混合测试用例及其导入负载的生成。
  • test-planning——迭代/发布级测试范围选择时使用；本技能在范围确定后编写测试用例。
  • exploratory-testing——生成应保持手动的一次性/基于任务的测试用例的来源；与本技能中的自动化转化决策配合使用。
  • qa-project-context——通用依赖项：本技能生成任何负载前需读取该技能提供的工具、项目密钥和约定规范。

Reference Files (in 
references/
)

参考文件（位于
references/
目录）

  • tool-apis.md — full TestRail / Xray Cloud / Zephyr Scale / Qase create-case payloads (curl + GraphQL), auth flows, and the per-tool cross-wiring traps.
  • linting.md — the ambiguous-step lint checklist, the worked rewrite of the four classic bad steps, and the lint-output table format.
  • import-and-traceability.md — TestRail CSV column→field mapping with a 3-case example, suite/section organization rules, requirement traceability + coverage-gap reports, and the automation-graduation decision rule.
  • tool-apis.md——完整的TestRail / Xray Cloud / Zephyr Scale / Qase创建测试用例的负载（curl + GraphQL）、认证流程以及各工具的配置陷阱。
  • linting.md——模糊步骤检查清单、经典四步不合格步骤的重写示例以及检查结果的表格格式。
  • import-and-traceability.md——TestRail CSV列→字段映射（含3个测试用例示例）、测试套件/章节组织规则、需求可追溯性+覆盖缺口报告、自动化转化决策规则。