SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsqa-testcase-designer

qa-testcase-designer

Design & creation

View repository

Updated 10-16 06:48

About this skill

QA Testcase Designer — Use Case Design and Confirmation

CLI Invocation Conventions: The CLI of this toolkit is quality-assurance-agent/scripts/qa_agent.py. Itis not distributed as a PATH command—commands are executed by you (the agent); humans do not need to type them by hand. Resolve the skill directory once before starting work, and from then on write all commands as python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path '*quality-assurance-agent/*' 2>/dev/null | head -1)")}"

If the runtime environment has already told you this skill directory (Claude Code will), use it directly; there is no need to run the lookup above. For the complete command syntax, see $QA_AGENT_DIR/references/cli-reference.md。

Your Positioning

This is theonly step requiring human confirmationin the QA pipeline. The qa-risk-analyzer before you tells you where the danger is, and the qa-test-script-generator after you turns your use cases into executable tasks—but if you get stuck here, the whole line will not move forward.

Your task is:turn the risk analysis into verifiable Chinese business use cases, show them to the user, and only proceed once the user says they are acceptable. Before the user nods, do not generate even a single line of test code.

CLI Commands

For the complete syntax and parameter descriptions of all commands in this phase, seemain skill (quality-assurance-agent) → CLI Command Reference → Phase 2. Command syntax is not duplicated here.

Prerequisites (all are required)

  1. .qa-agent/current/context.json exists
  2. .qa-agent/current/existing-case-index.json exists
  3. .qa-agent/current/risk-analysis.json exists

If anything is missing, go back to the upstream phase to fill it in. Reading manifest.json can quickly confirm the completion status of each phase.

Language Rules for Use Cases

  • Use case descriptions use Simplified Chinese: title, preconditions, steps, expected, businessActor, operationPath, businessStateBefore, businessAction, businessStateAfter, businessAssertions, risk—all human-readable fields are written in Chinese.
  • Keep as-is without translation: API paths, code identifiers, enum values, commands, URLs, file paths, account names, model names, and specific technical parameter values.
  • Use cases describe only business behavior: who, in what state, performs what operation, and what result is expected. Do not write "compilation succeeded", "all Maven tests passed", or "Playwright installation completed"—these belong in environment-checks or quality-gates.
  • Do not use uncertain expected results like "200/400"; if uncertain, read the code or write it into an open question.

Use Case Priority Rules

  • P0: involves financial loss, data inconsistency, privilege escalation, main flow blockage, state corruption, or settlement/payment/reward calculation errors. P0 use cases must all be covered in any acceptance round.
  • P1: core business rules and important regression scenarios.
  • P2: boundary values, invalid input, retries/timeouts, and non-critical exception paths.
  • P3: presentation details, copy, visual polish, and non-blocking compatibility.

Every P0/P1 risk (from risk-analysis.json) must map to at least one use case or one explicitly recorded open question. If you cannot do this, your work is not complete.

The mapping must fall into the use case's riskIds field (risk ID array, e.g. ["RISK-P0-001"]）——This is the only source read by the coverage projection. Only mentioning a risk ID in risk、traceability or in the prose does not count as an association; the report will count it as an uncovered gap. riskIds is empty while the risk is actually covered, the report will output a conclusion contrary to the facts.

Workflow

1. Load upstream materials

Read three files:

  • .qa-agent/current/context.json— know which code was changed, interface paths, data table structures
  • .qa-agent/current/existing-case-index.json— know the existing use cases, avoid duplicate generation
  • .qa-agent/current/risk-analysis.json— know where the dangers are, what assertions are needed

2. Load project experience

Read .qa-agent/knowledge/ for experience related to this scope, to guide use case design:

python "$QA_AGENT_DIR/scripts/qa_agent.py"show-knowledge --repo . --module <module> --category data-prep
python "$QA_AGENT_DIR/scripts/qa_agent.py"show-knowledge --repo . --module <module> --category api-quirk
python "$QA_AGENT_DIR/scripts/qa_agent.py"show-knowledge --repo . --module <module> --category test-pattern
  • data-prep experience guides you in designing the precondition data preparation for use cases (how to construct insufficient balance, expired assets, etc.)
  • api-quirk experience guides you in writing expected results (null fields omitted, business error codes in the response body, etc.)
  • test-pattern experience guides you in designing reusable verification methods

3. Generate use cases

First read $QA_AGENT_DIR/references/test-case-schema.md to confirm the complete field specification of the use case JSON (priority rules, verification rules, quality gate shape, environment check shape).

  • Prefer reusing existing use cases (the same ID and historical execution records remain unchanged)
  • Incremental generation only covers newly added or changed business operation paths
  • Each P0/P1 risk must have one use case or one open question
  • Write the draft to .qa-agent/current/test-cases.generated.json

4. Merge + validate

Run merge-existing-cases to merge the generated content with existing use cases into test-cases.json. Run validate-cases --summary --check-mojibake --strict-language. Validation errors must be fixed until they reach zero.

5. Render + review

Run render-cases to generate the HTML confirmation page. First read $QA_AGENT_DIR/references/model-review.md to understand the specific process and output format of the three-model review.

Run review-cases to do the three-model cross review. Valid findings in the review feedback must besynthesized and then test-cases.json modified— you cannot just run review once and submit as-is. For suggestions from the review such as missing boundary values, priority ratings, vague assertions, and missing negative paths, you must judge each one on whether to adopt it; adopt the ones you accept by changing the use cases, and record the reasons for the ones you do not adopt.

6. Encoding check

Run check-mojibake to perform an encoding integrity scan on all artifacts. On Windows, AI Write/Edit tools occasionally write U+FFFD replacement characters into Chinese JSON—if a problem is detected, use python "$QA_AGENT_DIR/scripts/qa_agent.py"safe-write-json --from-stdin to rewrite the damaged file through a Python pipeline.

7. User confirmation—this is a hard gate

Show test-cases.html to the user for review. Confirmation is not a procedural "run-through", but rather letting the user see item by item:

  • Each use case's title, priority, level, preconditions, operation steps, expected results, and covered risk IDs
  • Which P0/P1 risks are covered, and which have become open questions
  • The four elements locked by scope: scope / business main path / blockers / oracles

Do not make the confirmation decision for the user. You must wait for the user to give explicit affirmation ("pass" "confirm" "ok" "continue"). Before the user confirms:

  • Do not run promote-cases
  • Do not call qa-test-script-generator
  • Do not write any test scripts

8. Finalize after confirmation

Run immediately after user confirmation promote-cases, copy the confirmed test cases to .qa-agent/cases/<module>.json. This is the long-term knowledge base, to be reused in subsequent rounds.test-cases.json Keep it as the working copy of the current run.

9. Handover

Hand over the confirmed and solidified test cases to qa-test-script-generator. Note:P0/P1 risks and risk-analysis.json must be passed down together, the oracle and assertions of spec-task must be derived from here.

Encoding Safety

  • test-cases.json、test-cases.html、model-review.json All must pass through check-mojibake --strict
  • If you use AI's Write tool to directly write test-cases.json content, you must immediately perform a U+FFFD check after writing
  • If encoding corruption occurs multiple times, switch to python "$QA_AGENT_DIR/scripts/qa_agent.py"safe-write-json --from-stdin(write via Python pipe)

Fault Tolerance and Degradation

  • Missing upstream artifacts：context.json、existing-case-index.json、risk-analysis.json if any is missing → fall back to the corresponding stage to fill it in, do not fall back to a more upstream stage.
  • Three-model review unavailable: if a model call fails, complete the cross-review with the remaining models, and annotate the missing one in model-review.json .
  • Encoding corruption: all JSON/HTML artifacts must be rewritten via check-mojibake --strict。U+FFFD → safe-write-json .
  • Validation failure：validate-cases --strict-language failure → fix and rerun, do not bypass the validation.

Prohibitions

  • Do not write test code before confirmation. This includes not creating test files, not hand-writing spec-task, and not generating Playwright scripts. Confirmation is a hard gate.
  • Do not use purely technical checks such as Maven/build/install/compilation/tool queries as business test cases. Technical checks go in quality-gates or environment-checks.
  • Do not duplicate existing test cases. Existing test cases should be extended or reused, do not create duplicate test cases with new IDs.
  • Do not ignore the P0/P1 risks in risk-analysis.json. Each one must have a destination.
  • Do not mix draft test cases and confirmed test cases in the same file。
  • Do not treat test-cases.json as a long-term source of truth. After confirmation it must be promoted to the cases/ directory.