test-case-writing

Test Case Writing

From the requirements model (or raw input sources) and code, producehuman-readable, executablemanual test case files (markmap), and extract a machine-readable Test Case Schema for downstream Skills to consume.

Persisted artifacts：{项目}/测试用例_markmap.md(the sole manually maintained source) + {项目}/测试用例.schema.yaml(unidirectionally extracted from the markmap, rules see ../core/schema-extraction.md）。

When to Use

Has a code repository, needs to write test cases based on the actual implementation (code first, preferred scenario)
Given a requirements document/PRD, technical design document, API documentation, needs to write test cases
Given a Bug report, needs to write regression test cases
When requirements change, incrementally update existing test cases

When NOT to Use

End-to-end testing of the entire requirement (understanding→strategy→test cases→execution→report) → use the qa skill to orchestrate
Needs systematic requirements modeling (goals/scope/rules/exceptions/dependencies/ambiguities) → use the requirement-analysis skill; this skill only does lightweight input study
"How should this feature be tested" (strategy decisions on scope/type/depth/priority) → use test-strategy skill
Independent post-hoc reviewof existing or others' test cases → use the test-case-review skill; this skill only does self-review at writing time (Stage Four)
Writing automated test code → use the automated-e2e-testing(UI) or api-testing(API) skill
Determining regression scope after code changes → use the regression-testing skill; this skill is only responsible for incremental modification of test case files
Neither a code repository nor any requirements/design documents available for reference → cannot model or write test cases: first go through exploratory-testing exploration to build system understanding, or request input materials from the user

Workflow

Stage Zero: Proactively request the code repository (the first thing to do when starting work)

Before starting test case writing,proactively request the code repository of the project under test from the user：

Requested content: ① repository address (local path or remote URL); ② branch/tag under test; ③ scope of this change (PR/MR link or <base>...<head> diff scope, defaults to full if none)
Question template：

🔍 To improve test case accuracy, please provide the code repository address and branch under test of the project under test (if there is a PR/diff scope for this change, please also provide it). The code will serve as the functional fact baseline, and the documentation as a reference—test cases written based on the actual implementation can discover inconsistencies between documentation and implementation and locate potential bugs, which pure documentation mode cannot do.
User confirms no code → downgrade to pure documentation mode: prompt "Will write based on documentation, with limited accuracy: cannot discover inconsistencies between documentation and implementation, cannot locate potential bugs, cannot verify whether risk points have downstream consumers", skip "Code Exploration and Comprehensive Review" and Appendix Cx/Dn outputs.

The differences between code mode and documentation mode run through all subsequent stages, and each stage will be annotated.

Stage One: Input study + scope definition (code first)

Extract all testable points from the input sources, while identifying the platform, roles, and test boundaries.Code is the highest source of static facts(adjudication rules see ../core/evidence.md)——when code is available, the implementation prevails (test the declared behavior), and documentation is downgraded to a reference.

Input sources and focus areas

Input source	Key Focus
Code Repository (Highest Priority)	Actual implementation logic, data structures, error handling, deviations from documentation, potential bugs, change scope (diff)
Requirements Document/PRD	Feature list, boundary descriptions, user roles, business rules
Technical Design Document	Data models, interface signatures, state transitions, caching strategies, message formats
API Documentation	Interface parameters, required/optional, return values, error codes, authentication methods
Bug Report	Reproduction steps, root cause analysis, fix scope (regression test cases)
FAQ/Meeting Minutes	Implicit requirements, design decisions, boundary constraints

Key Reminders: Every question-and-answer in the FAQ is a potential boundary test case; constraints stated in "non-goals" declarations require corresponding verification cases.

Consume existing upstream artifacts directly: If 需求模型.mdexists (produced by requirement-analysis), use it as structured input, reference the clarification records directly, and do not re-model; if 测试策略.mdexists (produced by test-strategy), execute according to its scope/depth/priority requirements, and use the risk numbers in the Risk Map (R1, R2…) as risk_ref attached to the corresponding test cases. If type_scope (type domain decision) exists, execute according to the consumption mapping in ../core/test-type-matrix.md Section 12:Case-basedaxes (business security/reliability/concurrency/compatibility, standard and above) produce corresponding type test cases—use security / reliability / concurrency / compatibility for type, add to the name line [并发] and other labels (for i18n/migration/contract axes use type: functional + labels);Script-basedaxes (performance/visual, standard and above; accessibility at any tier produces axe scan tasks and violation lists) do not produce manual test cases; annotate in the overview section that "execution artifacts go through dedicated scripts" and leave it to the execution strategy for adjudication;Review-based(light tier) findings are merged into Appendix Cx review checklist; exclude axes produce nothing.

Identify Scope

Record synchronously while reading input sources:Platform/End(admin backend, user end, backend API, third-party callbacks),User Roles(what each role can see, can do, and cannot do),Test Boundaries(current scope vs. not tested vs. dependencies).

Audience and Execution Model Determination (Mandatory at Start, Determines How Test Cases Are Written)

Whether the feature under test has a UI directly determines how the test case body is written. Determine this at the start;When it cannot be determined from input sources whether there is a UI, confirm with the user in one sentence:

Features with UI(web admin backend, App, mini-program, H5 pages) → Test engineersexecute independently. Operation steps should describe specific UI actions (which page to enter, which field to fill, which button to click); expected results should describe phenomena observable on the page.
Backend features without UI(data stage, API interfaces, SDK migration, scheduled tasks, message queue consumption) → Test engineerscannot execute independently, write it as a **"Test-Development Collaboration Checklist"**: mark operation steps as "Please have development execute" (give development the specific data and trigger method); mark expected results as "Please have development report back" (report actual values/screenshots); mark verification methods as "Development checks the database/checks logs and reports back".Ask at the start of work: Confirm the execution model with the user ("Can testing be executed independently? Backend features usually require development to run them on their behalf + report back from database checks, right?").

Regardless of which model is used,the test case body must use business language(for format details see ../core/case-format.md, phase three execution).

Code exploration and comprehensive review (exclusive to code mode, mandatory when code is available)

Execute 4 steps on the basis of document study to build a project map and discover potential bugs. This step produces the "code basis" and defect record foundation for subsequent test cases.

Step 1 — Locate and get an overview: Confirm the repository path/branch under test/scope of changes; read the README, route table, entry files, and configuration files to build a project map.

Step 2 — Change inventory：git diff <base>...<head> --stat List changed files and classify each one: 🆕 New (new feature mainline, full coverage), ✏️ Modified (source of regression risk, focus on covering whether the original behavior is preserved + new behavior), 🗑️ Deleted (feature offline, verify there are no residual entries after going offline), 💀 Dead code (unmounted routes/unreferenced, mark as ignorable). Produce a "changed file → affected module → regression test case" mapping (record it in the appendix "Changed File Mapping").

Step 3 — Comprehensive code review (dispatch an Explore agent matrix, always execute)：

Split by number of changed files/subsystems, dispatch 1–3 read-only Explore agents in parallel; each agent focuses on one type of finding. Example agent prompt framework: "Review {仓库路径} {分支} {file/subsystem list}, search item by item against the following checklist, and attach 文件:行 evidence for each finding and mark confidence: ① potential bugs; ② inconsistencies between documentation and implementation; ③ dead code/dead declarations; ④ suspected high risk but possibly no downstream consumption (need to verify whether it is disproven). Read-only, do not modify."

Review checklistExecute ../core/coverage.md all 13 items in Section 7.1 "Code Review Finding Pattern Checklist"(null/undefined not handled, boundaries unprotected, state deadlock, concurrency race, errors silently swallowed, etc.), not an optional reference.

Step 4 — Risk grading + conversion：

High-risk points D1-Dn: According to ../core/risk-model.md grading (Impact × Likelihood → Critical/High/Medium/Low), map each one to a regression test case
Potential bug → Defect record Cx: ID + phenomenon + evidence (E0–E4 level + 文件:行, for format see ../core/evidence.md) + disposition (mainline verification / special verification / pending actual test confirmation / disproven / backend scope)
Documentation deviation: record in the appendix "Documentation Deviation Comparison";dead code: mark as ignorable, do not write test cases

Degradation strategy when input sources are missing

Only PRD and no design document → do not check for "inconsistency between PRD and technical design", and skip the "technical implementation details" dimension during the review phase
Only API documentation → use interface parameters and error codes as the main input sources, focusing on covering input validation and error handling (for methods see ../core/methods/data-driven.md）
Only bug reports → focus on regression testing, expanding around the functional areas involved in the bugs

Phase 2: Requirements Clarification

After the document study is complete,you must first check whether there are any ambiguities, incompleteness, or contradictions, and must not make assumptions on your own.

The single authoritative source for triggers and scanning is in ../core/clarify-pattern.md(loaded at this point): basic triggers follow its "when it must be asked", and deep scanning screens category by category according to its "nine categories of requirement ambiguity escape patterns" A–I (this phase no longer maintains an independent checklist).

Code-mode-specific triggers(not applicable in document mode):inconsistency between document and code—data structures, whether fields are submitted, process order, default values—by default the code prevails (test-accurate declaration); list the original text from both sides and ask "is the deviation confirmed to be a non-defect?"

The question format and ruling recording rules uniformly follow ../core/clarify-pattern.md: each item becomes an independent card, suggested options are provided, and the user's reply is recorded in the clarification record.

Output: no clarification needed → confirm in one sentence that "the requirements are sufficiently clear" (merge into the introduction,do not list a separate clarification section, do not produce a ceremonial checklist—a clarification ceremony on clean material is a pure output budget cost, and in practice it has caused the overall net benefit to be negative), and proceed directly to Phase 3; if there are issues → list the issue checklist,wait for the user's reply before proceeding to Phase 3; if new issues are found during subsequent writing → ask additional questions at any time, do not force the writing. The clarification record aligns with the open_questions field of the requirements model (the user's ruling has final decision authority, see ../core/evidence.md ruling rules).

Phase 3: Use Case Writing

Directly output the final use case file, without producing any intermediate files (no outline, no matrix table). Use the markmap format (Markdown heading hierarchy + lists).

Module-by-module progression and delivery verification (hard constraint)

Write module by module:only after each module heading has use cases may you proceed to the next module(a complete skeleton is not required first—write directly module by module).Before delivery, verify module by module against the input materials: every functional module in the input (including easily missed sections such as FAQ, exception handling, permissions/roles, scheduled tasks, etc.) has a non-empty module with use cases in the output; empty modules must be filled in, or the blocking reason must be explicitly recorded in the pending clarification list before finalization.Delivering after completing only the first module when the input has multiple modules = the most serious delivery defect.

Dimension verification (item by item, at the same level as module verification)—complete modules but missing dimensions also block finalization:

The main flow cannot be omitted: the shortest positive main path for each function (the simplest operations such as create/submit/initiate) must have at least 1 use case—"too obvious" is not a reason to omit it;
Both sides of time: each time-related rule (time limit/validity period/timeout/automatic trigger) must have at least 1 two-sided boundary use case (one tick before the boundary can succeed / after reaching it enters another state)—when the time limit value is already given in the materials, both sides are still required(e.g., "30-minute timeout" → payable at 29 minutes 59 seconds, closed at 30 minutes 00 seconds; "7-day automatic confirmation" → can be manually confirmed one second before 7×24h is reached, automatically confirmed after reaching it). A given value does not equal verified; the behavior exactly at the boundary moment is an independent use case;
Negative baseline: State machine model input, with at least 1 negative case each for illegal transitions and terminal-state constraints.

Discipline basis: change "completeness" from a post-review discipline in phase 4B to an explicit pre-delivery checklist item—post-hoc discipline may be skipped in weak execution environments, and per-module checks block the early stop of "finish writing one module and call it done." But after module checks block module collapse, weak models will still exhibitdimension collapse—modules are complete but dimensions are empty, so the check must drill down to dimensions.

Output budget discipline (hard constraint)

The output budget is limited (32K token level),ceremony and use cases compete for budget—use cases take priority：

Cap on number of use cases：min(可测点数 × 1.5, 80) is the upper limit; when exceeded, shrink by P0 > P1 > P2, without diluting the quality of a single case (the four-part structure must not be omitted) just to make up the count;
Test data obeys constraints: the test data in use cases (unique names, accounts, order numbers, etc.) must satisfy the field constraints declared in the materials (maxLength/enum/format)—the total length of the generated data template should reserve margin against the constraint upper limit, not push it to the limit (measured self-inflicted case: the unique-name template for an API task was 22 characters and hit the contract maxLength 20, causing the entire use case to fail with NAME_INVALID); parameter matrix combinations must also satisfycross-field business rules(such as "the usage threshold cannot be lower than the face value," "the start time is earlier than the end time")—when changing each parameter independently, recheck all rules for each grid combination; grids that violate the rules should be changed to valid values or split into explicit negative cases (measured self-inflicted case: an amount at the upper limit of 1000 paired with a threshold lower than the face value was correctly rejected by the business rule while the use case expected success);
The appendix is produced only in code mode, while pure document mode does not produce Cx/Dn/change mapping/code evidence checklist (there is no code to cite);
Reader's guide compression: each of the four items is ≤3 lines; the glossary includes only terms actually appearing in the body;
Content in a single use case that goes beyond the four-part structure (background explanation, method argumentation) must all be deleted—details belong to the clarification record or appendix, not to the use case.

Basis: api-testing's output budget discipline (parametrize convergence/line limit) is the only measured anti-truncation means in the entire set; in measured practice there was an incident where output was truncated leaving only one { , sharing the same root cause as the clarification ceremony overhead—budget awareness must be extended from api-testing to this skill.

Design method selection (load at this point `../core/testing-principles.md`）

Choose methods by functional characteristics; state machines are not mandatory: obvious state transitions → State Machine; input-output type → equivalence classes + boundary values; permission system → Role×Action×Resource; API → parameter matrix; complex business process → Workflow; data transformation → Input→Transform→Output; many historical bugs → regression focus.

Organization and format (at this point execute two hard-constraint files, not optional references)

Organization: organize modules by state transition and operation lifecycle (method execution ../core/methods/state-machine.md: extract the state machine → split modules by state node → one use case per edge + illegal transitions/races/reverse edges → independent module for cross-cutting concerns). For functions without state transitions, organize by ../core/methods/boundary.md / ../core/methods/data-driven.md / ../core/methods/permission.md corresponding methods, loaded according to input source characteristics.
Format：Execute ../core/case-format.md all format hard constraints—the four-part reader's guide at the top of the file, zero code internals in the body, TC numbering (TC-{模块号}-{序号}, add for P0 （SMOKE-n）), four-stage/collaborative five-stage, front-loaded de-duplication, embedding concrete data (placeholders prohibited), page reachability, asynchronous decision time limits, assertion scope ≤ verification strength, testability annotation, test-accuracy declaration (code mode), appendix area specification (Cx/Dn/code evidence list/document deviations/changed-file mapping, physically isolated from the main text). For the assembly starting-point template, see templates/markmap_template.md。

Priority Rules (strictly enforced)

Annotate on the test case name line [P0]/[P1]/[P2]; when not annotated, the default is P1.

P0 (smoke)— satisfies the followingallconditions: the core path of the main flow; if it fails, the entire feature is unavailable;P0 self-check(execute item by item): if this test case fails, can the user complete the core operation? Only when the answer is "no" is it P0.

P1 (regular): normal function verification + common exception handling.P2 (boundary): extreme inputs, low-frequency scenarios, requiring special environments. Performance-type requirements are not included here—performance is the script-type axis of the type matrix (Axis 1); standard and above go through dedicated scripts, light goes through Cx review items, and no tier produces manual test cases.

When a Risk Map exists, execute according to the mapping suggestions of ../core/risk-model.md ; deviations must be justified. (Note: the two real-world self-inflicted cases in §3 of this skill and the api-testing engineering conventions each keep a copy from the same source—Red Line 4 requires each to be self-contained, and revisions must be synchronized in both places.)

Stage Four: Review (spot-check while writing)

Downgrade rationale: full-inspection 4A/4B is pseudo-execution under weak models × output budgets (in practice it consumes a large amount of verification budget without changing output behavior). The covered execution points have been migrated to Stage Three delivery verification (module verification + dimension verification, inlined in the generation path), this stage only does lightweight spot checks and does not return to the original document for paragraph-by-paragraph comparison (that instruction is a thinking-budget killer and has been abolished).

4A: Spot check after a module is written (do only two items)

Spot-check the main flow: whether test cases exist for the shortest positive main path of this module (same criterion as item 1 of dimension verification; here it is only a recheck)
Spot-check single responsibility: spot-check 2-3 test cases to confirm they test only one point and have a unique expectation

4B: Global spot check (after all modules are completed, do only three items)

FAQ/non-goal spot check: at least 1 test case for each FAQ item (a high-incidence area for omissions)
Second-order cross spot check(for medium-sized and larger projects):../core/testing-principles.md select 1 of the three items in Section 3 to execute (write path × validation / failure × retry / identifier × duplication)
Cross-module duplication check: merge duplicate test cases, keep TC numbers consecutive

Abolished: full document-by-document traceability inspection, full 19-dimension inspection of coverage.md, full four-perspective inspection by multiple roles—thedesign knowledge of these dimensions is still in ../core/coverage.md(reference on demand, for strong models/large projects to deepen), but is no longer a mandatory pre-delivery execution item; the only mandatory execution items are module verification + dimension verification in Stage Three delivery verification.

Review output

Directly supplement omissions and make adjustments in the test case file, without producing a separate review report. Only at the end of the test case file (after the appendix), append a "Review Record" according to the format in Section 10 of ../core/case-format.md .

Phase 5: Finalization + Schema Extraction

Readability self-check：Execute ../core/executability.md all check items(zero-context newcomer retelling, glossary verification, main text zero-code self-check, executability confirmation, judgment time limit check), not an optional reference
Schema extraction: unidirectionally extract from markmap 测试用例.schema.yaml—field definitions, extraction rules, and YAML escaping discipline are unified in ../core/schema-extraction.md(loaded at this point); after extraction run ../core/scripts/validate_schema.py 测试用例_markmap.md 测试用例.schema.yaml --strategy {策略路径}/测试策略.md validation (YAML validity + TC number consistency + placeholder check + risk coverage gate: all Critical/High risks in the Risk Map must be reverse-covered by the risk_ref of ≥1 test case; zero coverage means the gate fails; if there is no upstream policy file, omit this parameter. If a code repository is available, additionally --repo-root spot-check the authenticity of what code_refs refer to)
File naming:{项目名}/测试用例_markmap.md + {项目名}/测试用例.schema.yaml

Schema dual-track principle

markmap is the deliverable for humans and thesole manually maintained source; Schema is the machine-readable metadata layer, unidirectionally extracted by this skill from markmap unidirectionally extracted, serving as the inter-Skill transfer interface (test-case-review / regression-testing / consumed by the execution layer).No requirement for humans to maintain two copies, Schema can always be regenerated from markmap; after markmap is modified it must be re-extracted. Existing markmaps can simply be extracted according to the same rules, with no manual rewriting needed.

Incremental update process

When requirements change, incrementally update existing test cases (rather than rewriting from scratch):

Impact analysis: determine which modules and which test cases the change affects (direct test cases + downstream dependencies + edges affected by state transitions + queries/validations affected by data model changes). Code mode: based on git diff inventory the changed files, and locate affected test cases by category according to the appendix "Changed File Mapping"
Mark affected test cases: list them by TC number, mark [已变更]、[已废弃]、[需新增](Schema's status synchronized)
Update test cases: for new additions use appended numbers, for deprecations use ~~删除线~~ + [已废弃-原因]
Local review: execute 4A + cross-module checks involving the change for the changed modules
Re-extract Schema(and run ../core/scripts/validate_schema.py validation), output a change report (format see ../core/case-format.md Section 10)

Common Mistakes

Error	Consequence	Correct practice
Writing test cases directly without requirement clarification	Test cases are based on wrong assumptions, wasting rework	Ask questions immediately when ambiguity is found
Having code but not reading it, relying only on documentation	Test cases are based on wrong assumptions (documentation often does not match the implementation)	If code exists, it must be read; the implementation prevails (test the declared behavior)
Producing non-executable test cases (placeholders/fabricated entry points/asynchronous without time limits)	Dead test cases take up space, and executors cannot start work	Execute `../core/executability.md` all hard standards
Test case main text piled with code internals (`文件:行`/SDK symbols/error code constants)	Test engineers cannot understand it and cannot execute it	The main text uses pure business language, with code evidence isolated in the appendix (`../core/case-format.md`）
No-UI backend features copy the UI use case and write "operation steps"	Tests cannot be executed independently; steps are left dangling	At kickoff determine the execution model; for no-UI write the five-part collaboration format
Missing the reader's guide section (terminology/environment accounts/legend)	Someone who has never touched the project gets stuck at the very first step	The reader's guide four-piece set; for unknown information list a TODO noting who to get it from
Validation cases only cover the create path	Bugs that bypass validation on the edit/resubmit path go untested (high incidence)	Second-order cross-check: write paths × validation rules checked cell by cell
Async cases have no decision time limit	Pass/fail is decided by the executor arbitrarily	Expected results must state the time limit; if there is no basis, list it as a clarification question
Trusting documents/verbal descriptions; risk points not verified against code	Writing pseudo cases (e.g., the already-disproven "gating deadlock")	Verify the downstream consumer for each risk point, rate according to `../core/risk-model.md` and attach evidence
Only testing functionality, not checking for potential bugs	Missing defect verification; bugs only surface once live	Comprehensive code review (`../core/coverage.md` 7.1 pattern checklist); convert potential bugs to Cx
P0 flooding or absence	Smoke tests lose their screening value	Execute the P0 self-check questions one by one
Ignoring the FAQ/non-goal statements	Missing boundary cases	At least 1 case per FAQ entry

Collaboration with other skills

Upstream：qa(end-to-end orchestration) → requirement-analysis(requirements model) → test-strategy(strategy + Risk Map) → this skill. If upstream artifacts exist, consume them directly; if not, inline a lightweight version (just enough)
Downstream：test-case-review(post-hoc independent review) → automated-e2e-testing / api-testing(consume cases and Schema to execute) → regression-testing(consume code_refs / risk_ref to perform impact analysis)
Shared methodology and format standards are in core/(design methods core/methods/, coverage checklists, case format, Schema extraction rules); this skill's private assets are only templates/markmap_template.md(assembly starting point)
Outputs of this skillManual test cases + Schema; suspectedsuspecteddefects found in review are recorded as Cx (to be verified); root cause analysis of confirmed bugs belongs to bug-analysis