Quick Summary
Review modes: For review/audit work, standalone defaults to
--review-only(--report-onlyalias);--fix-loopenables review → validate → authorized fix → fresh re-review, default cap 3.--fix-loop --loop-owner=callerreturns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carriedreview-policycontract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.
Goal: Generate, review, diagnose and verify integration tests that protect the selected case contract through real boundaries and system-owned outcomes.
Summary:
- Select the invocation route before applying its procedure: no flag uses from-changes, from-prompt, positional review, diagnose or verify-traceability;
--mode=reviewsupports review-only or the shared fix-loop;--mode=verify [--fix-loop]owns runtime proof. - Resolve the case profile and package before judging coverage. Generate: owner cases → tests → full-scope traceability. Review: scope/profile → package → eight gates → validate/deduplicate → verdict/report → stop. Verify follows its reference's repeat/isolation and failure rules.
- Preserve meaningful assertions, production fidelity, native carriers/cardinality and operation authority; blocked or unknown evidence never proves coverage.
Workflow: Detect → find targets → gather context → execute the selected mode → report.
Key Rules: Read the selected mode reference in full; preserve task order and evidence; defer test execution to its final proof owner. See Mode Dispatch for flags, references and execution location.
[BLOCKING] Mode routing — detect FIRST. Explicit
--mode=reviewor--mode=verifyselects its standalone procedure; no flag selects generation. Each flagged mode works directly without a workflow. Read its reference in full before executing (see Mode Dispatch)./integration-test-reviewand/integration-test-verifydo not resolve.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run,
/start-workflow→ Workflow-step mode bounds this rule. [BLOCKING] Before each step or sub-skill call, update todo tracking: setin_progresswhen step starts, setcompletedwhen step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Sub-Agent Selection: Integration work routes to
integration-tester; specialized work uses matching agents; parallel waves require disjoint writes and all-return barriers. MUST ATTENTION READ.claude/skills/shared/sub-agent-selection-guide.mdbefore delegating.Overlay Registry: Exact > glob > all; derive bodies from
Nameinside the protocols directory; overlays add constraints and never waive framework gates. MUST ATTENTION READ.claude/skills/project-skill-protocol/references/registry.mdwhen resolving overlays.
Contents
- Quick Summary
- Case Contract Profile Gate (BLOCKING)
- Mode Dispatch
- First Principle — Easy to Change · Easy to Scale · Easy to Maintain
- Project Pattern Discovery
- Native-Profile Task Ordering
- Mandatory Task Ordering (Strict TC Default Only)
- Module Abbreviation Registry
- TC Code Numbering Rules (Strict TC Default Only)
- Integration Test Generation
- Mode Detection
- Step 1: Find Targets
- Step 2: Gather Context
- Step 2b: Look Up TC Codes (Strict TC Default Only)
- Step 2c: Real-World Fidelity Check (BEFORE any test code is written)
- Test Architecture Contract Preflight (before Step 3)
- Step 3: Generate Test File
- Step 4: Verify
- Example Files to Study
- REVIEW Mode — Test Quality Audit
- DIAGNOSE Mode — Test Failure Root Cause Analysis
- VERIFY-TRACEABILITY Mode — Test ↔ Spec ↔ Feature Doc Verification
- Test Data Setup Guidelines
- Test Execution & Failure Diagnosis (MANDATORY)
- Next Steps
- Related Skills
- Standalone Chain
- Prompt-Enhance Closing Anchors
- Closing Reminders
Case Contract Profile Gate (BLOCKING)
Before mode detection, test generation, or any spec/test mutation, read docs/project-config.json, docs/project-reference/docs-index-reference.md, docs/project-reference/lessons.md, the required local spec/integration-test references, and this skill's matching references. Resolve one profile:
- Strict TC default: neither config nor required project references explicitly declares a different canonical case owner, identity, carrier, section role, or case-to-test relation. Use the default Section 8 /
TC-{FEATURE}-{NNN}procedure below. - Native profile: config or a required project reference explicitly declares a different case contract. A missing optional profile field in config does not erase an explicit contract in a required reference. Use the native owner and the declarations below; do not create Section 8 or a duplicate TC registry.
- Unresolved: config is invalid/incomplete, required references conflict, or owner/identity/carrier/cardinality cannot be resolved. Report
BLOCKED/UNKNOWN; do not infer a profile, fall back to TCs, generate tests from guessed intent, or claim coverage.
A changed root, template, filename, or test directory alone does not select a native case profile.
Read references/integration-test-native-profile.md when the profile resolves to Native; it holds the native-profile crosswalk for owner and scope, identity, test carrier, cardinality, coverage proof, reports and matrices, missing or changed intent, and test result.
The semantic floor is identical in every profile: MUST ATTENTION retain authored expected outcomes, assertions that fail when protected intent breaks, property plus boundary coverage for universal invariants, relevant authorization and preservation cases, real production paths, repeatability, operation authority, and spec/test/code drift adjudication. The strict-default procedures and report examples later in this file are conditional on selecting that profile; adapt their evidence and output fields to a native profile without dropping these gates. Matched project overlays add constraints and cannot waive a shared skill gate.
Key Rules:
- AI surface? Only if the code under test creates or changes a model call, prompt, agent, tool/MCP, retrieval or eval (see
node .claude/scripts/ai-signal-scan.cjs): read.claude/skills/shared/protocols/ai-engineering-gate.md, applyAE-6(model mocked at one seam, property asserts, no live paid calls in default CI); otherwise skip this line. - NEVER write smoke-only tests — trace the affected production boundary and assert the externally observable contract or relevant persisted state
- For async/eventually consistent outcomes, use the configured synchronization/polling helper; for synchronous persistence, assert with the project's normal deterministic read path
- Use the production entry path when that is the behavior under test; use project builders/factories/fixtures or other valid setup for unrelated preconditions, without skipping the tested contract
- MUST ATTENTION apply the Real-World Fidelity Gate BEFORE writing setup — a sequence, pacing, or data shape production can never reach proves nothing when green; fix the SCENARIO, never the assertion
- MUST ATTENTION search existing patterns FIRST before generating any test
- MUST ATTENTION READ
references/integration-test-patterns.mdbefore writing - Organize tests using the project's established domain/module convention; do not impose CQRS folders or feature folders when the project has no such organization
- Every test method MUST carry the traceability form required by the selected profile. The strict default uses
TestSpecfor business §8 coverage andTechnicalSpecfor technical-only regression coverage; only that profile auto-creates a Section 8 case for genuinely uncovered business behavior. - Derive case count from distinct behaviors, invariants, risk, and meaningful boundaries; do not enforce an arbitrary minimum per command or endpoint
- Follow
integrationTestVerify.guidance; when absent, require two fresh no-reset runs for suites with persistent/shared state before declaring that scope repeatable
Mode Dispatch
Select from invocation arguments; load only the selected mode's references in full before work. The Case Contract Profile Gate still applies before interpreting cases or mutating specs/tests.
| Mode | Purpose | Read in full FIRST |
|---|---|---|
| (none) | Default test generation/authoring with positional review, diagnose and traceability branches | This file; positional references below when selected |
| `--mode=review [--review-only | --fix-loop] [--prove-tests] ` | Review through eight quality gates; report-only default or shared fix-loop with fresh re-review |
--mode=verify [--fix-loop] <target> |
Runtime proof under the configured repeat/isolation policy; optional failure convergence | references/mode-verify.md; also references/fix-loop.md before any --fix-loop work |
- [BLOCKING] When
--mode=verify, readreferences/mode-verify.mdin full FIRST; it replaces test generation for the invocation and owns--fix-loop(readreferences/fix-loop.mdin full before any loop work). Without--fix-loopthe default verify pass runs exactly as documented there. - Flagged modes replace generation for the invocation and govern their own caps, flags and terminal states. Without
--fix-loop, use the default verify pass. Review workflow calls return the verdict/report path without next-step prompts. - Positional
review/diagnose/verifyare generation branches. Workflow gates always use--mode; generation never chains into flagged review/verify on its own. execution-mode: subagentapplies to generation. Verify runs INLINE in the main session, including--fix-loop; review runs where its caller dispatches it, including a read-only specialist underworkflow-review-changes.
Prerequisites — MUST ATTENTION READ before executing:
references/integration-test-patterns.md— canonical templates: collection attributes, base classes, default traceability annotations, async polling, unique names, DB assertions. Read before writing ANY test and apply project-declared carriers when a native profile is selected.The canonical business owner root (default
docs/specs/;specRoots.business.pathindocs/project-config.jsonoverrides the path) — read its existing cases and identity rules before generation. The strict default uses TC IDs.
- MUST ATTENTION READ
references/integration-test-patterns.md,domain-entities-reference.mdfrom the configured reference-docs root, and the canonical business owner root before generation; use the pattern doc for code conventions and the selected owner for case traceability. The strict default checks Section 8 TCs.
CRITICAL: Search existing patterns FIRST. Grep same-service integration tests before generating; read ≥1 to match namespace/imports, collection, base class, and helpers. NEVER contradict established patterns.
CRITICAL: NO Smoke/Fake/Useless Tests. Each test MUST cross the actual integration boundary it claims to cover and assert a meaningful system-owned outcome. Before assertions, trace the production entry point, contract owner, and observable effects; inspect handlers, entities, events, messages, or persisted records when those concepts exist in the selected architecture.
CRITICAL: Synchronize with asynchronous outcomes. When the selected behavior completes through background work or eventual consistency, wait on an observable completion signal with the configured helper and bounded diagnostics. For synchronous behavior, use the project's normal deterministic assertion path. Never retry a failing final assertion to hide a product defect.
For test specifications and test case generation from tasks, use
/spec [mode=tests]skill instead.
Invariant coverage. For rules that must hold across a broad input domain, prefer property/metamorphic checks plus relevant boundary counter-cases when the project's test tools support them; retain example-based cases for concrete user scenarios. Trace each check through the selected canonical carrier, and use Section 8's Invariant/Property TC only under the strict default profile. Use mutation results as evidence of assertion strength, not as a universal required tool.
External Memory: Complex/lengthy work → write findings to
tmp/reports/to survive context loss.
Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim needs
file:lineor traced evidence; confidence >80% acts, <80% verifies first.
First Principle — Easy to Change · Easy to Scale · Easy to Maintain
The full gate is
SYNC:core-engineering-principles(protocol guide below; a hook delivers its text); its closing digest ends this file.
Project Pattern Discovery
Applicability first: Resolve the project's actual runner, boundary and fixture model. Collection/category attributes, DI containers, user-context factories and database helpers below apply only when that runner and tested contract use them; otherwise record N/A and keep the native harness/fixtures/assertions. Test names and traceability use the project's format. Never invent a service, database, auth actor or framework to satisfy an example.
Before implementation, search codebase for patterns:
- Search:
IntegrationTest,TestFixture,TestUserContext,IntegrationTestBase - Look for: existing test projects, collection definitions, service-specific base classes
MANDATORY IMPORTANT MUST ATTENTION plan task to READ
integration-test-reference.mdfor project-specific patterns and code examples. If not found, continue with search-based discovery.
Workflow:
- Detect mode — See Mode Detection below
- Find targets — Identify test/command/query files
- Gather context — Read relevant files for detected mode
- Execute — Generate, review, diagnose, or verify
- Report — Build check (generate), quality report (review), root cause (diagnose)
Key Rules:
- MUST ATTENTION search existing test patterns in same service BEFORE generating
- MUST ATTENTION READ
references/integration-test-patterns.mdbefore writing any test - Organization follows the project-native convention. Where it groups by domain, colocate related command/query cases; do not impose or prohibit CQRS folders against documented organization.
- Use project uniqueness helpers for data in shared mutable namespaces; deterministic values are valid in isolated fixtures.
- Use project assertion helpers for persisted outcomes; synchronization follows the tested boundary
- CRITICAL MUST ATTENTION: Exercise the production entry path when it is the boundary under test. For unrelated preconditions, use the project's valid fixtures/builders/seeders without bypassing the protected contract.
- Synchronization: use observable condition-based barriers for asynchronous/eventually consistent outcomes, with a bounded timeout; deterministic synchronous persistence uses the normal read/assert path. Never mask a synchronous defect with retries.
- CRITICAL MUST ATTENTION: Before assertions, READ handler/entity/event source; identify changed fields, created/updated/deleted entities, and fired handlers. Smoke-only is FORBIDDEN unless side effect is truly unobservable.
- CRITICAL MUST ATTENTION: Follow the configured repeat policy. Without one, persistent/shared-state or async suites need two fresh green runs; isolated deterministic suites use the runner's normal fresh run. Clean up only owned fixture state.
- Derive test cases from distinct protected behaviors, relevant failures and boundaries; a database check is required only when persistence belongs to the tested contract
- Authorization tests: When access control belongs to the tested contract, verify allowed and refused actors through the project's actual identity mechanism.
- Strict default only: every business test method has
// TC-{FEATURE}-{NNN}: Description+TestSpec; technical-only tests useTechnicalSpec; one TC may map to many methods. - Strict default only: when a genuinely uncovered business behavior has no TC in the feature doc, add it to Section 8 before generation; never mirror a method already covered by an existing TC. Native profiles update only their declared owner/carrier through the native-profile sequence above.
- For comprehensive spec generation before coding →
/spec [mode=tests]first
Native-Profile Task Ordering
Read references/integration-test-native-profile.md when the profile resolves to Native, before creating tasks; it holds the Native-Profile Task Ordering (FIRST owner cases, MIDDLE tests, FINAL two-way reconciliation, the zero-GAP/UNKNOWN coverage matrix task, and the missing-contract rule) that replaces the strict ordering below.
Mandatory Task Ordering (Strict TC Default Only)
ALWAYS create and execute tasks in this exact order:
FIRST: Verify/upsert test specs in feature docs
- Read feature doc Section 8 (
{App}/README.{Feature}.mdunder the business spec root — defaultdocs/specs; aspecRoots.business.pathentry indocs/project-config.jsonoverrides the path) for the target domain. - Verify matching
TC-{FEATURE}-{NNN}for each test case. - Missing → create Section 8 entry with Priority, Status, GIVEN/WHEN/THEN, Evidence.
- Incorrect → update to current behavior.
- Output TC → test-method mapping. One TC may map to many methods across components/services;
TestSpecis the join key.
- Read feature doc Section 8 (
MIDDLE: Implement integration tests
- Generate files from task 1's TC mapping.
- Put the configured test-framework TC annotation before each method, outside its body.
- Follow existing test base-class patterns.
FINAL: Verify traceability (1 TC : N tests) — WHOLE feature area, not only this run's TCs
- Grep test-spec annotations across all integration and unit suites; integration-only searches falsely orphan unit-covered TCs.
- Grep every
TC-{FEATURE}-{NNN}in Section 8 of all implicated feature docs, including untouched/pre-existing TCs. - Verify: each business method → exactly one doc TC (
TestSpec); each technical-only method →TechnicalSpec; each doc TC → ≥1 test. Many methods may cover one TC; NEVER require 1:1 or split/technicalize a business TC (M1/M5; seetc-format.md→ TC ↔ Test Code Cardinality). - Flag orphans:
TestSpecTC absent from §8; technical-only method with businessTestSpec; doc TC with zero tests. Many tests sharing one TC is NOT an orphan/duplicate. - Update each TC's
CoveredBywith{File}::{MethodName}comma-separated on one line, or a large-set filter (field representative; code annotation authoritative). Unit tests MAY be included. LegacyIntegrationTest:is migration input only.
MANDATORY task — "Validate: no missing integration tests" (non-skippable inside a workflow, with staged/unstaged git changes, or by direct request — essentially every run; only exception: narrow read-only single-TC lookup with no generation). Create as its OWN named
TaskCreateitem, not folded into step 3. Run the same bidirectional logic as VERIFY-TRACEABILITY, scoped to the feature area:- Every changed command/query/handler/entity/event-handler file has ≥1 covering test (grep + read; name match alone NOT coverage).
- Every
TC-{FEATURE}-{NNN}in the FULL Section 8 set of implicated feature docs has ≥1 covering test. - Emit a table; require zero GAP rows before done:
TC / Changed File Covering Test(s) Status TC-{FEATURE}-{NNN} or {file:line} {file}::{method}[, …] / NONE COVERED / GAP Any
GAProw → generate the missing test (return to Step 3) before marking the taskcompleted. Do NOT report done with an open GAP.
Module Abbreviation Registry
Discover existing feature/module codes from the selected canonical business owner and its index; discover test folders from the project’s test organization. Do not copy generic module abbreviations into a project registry. The strict-default feature doc remains the numbering owner below; native profiles retain their declared identity and cardinality.
TC Code Numbering Rules (Strict TC Default Only)
Creating new TC-{FEATURE}-{NNN} codes:
- Check feature doc first —
{App}/README.{Feature}.mdunder the business spec root (defaultdocs/specs; aspecRoots.business.pathentry indocs/project-config.jsonoverrides the path) has existing codes. New codes must not collide. - Decade-based grouping — e.g., OM: 001-004 (CRUD), 011-013 (validation), 021-023 (permissions), 031-033 (events). Find next free decade.
- Unavoidable collision → preserve the owner-qualified scenario identity where possible. If renumbering is required, migrate the canonical ID and every configured carrier/reference atomically, preserving variants and declared many-to-many mappings. Inspect the executing assertions and verify that every migrated case still joins to its intended executor. If either owner/carrier is ambiguous or outside authorized ownership, stop and coordinate before claiming traceability; a prose note is not an alias.
- Feature doc = canonical registry. Test-spec annotation = traceability only, not numbering source.
Integration Test Generation
Mode Detection
Args = command/query name (e.g., "/integration-test CreateOrderCommand")
→ FROM-PROMPT mode: generate tests for the specified command/query
No args (e.g., "/integration-test")
→ FROM-CHANGES mode: detect changed command/query files from git
Args = "review" (e.g., "/integration-test review Orders")
→ REVIEW mode: audit existing test quality, find flaky patterns, check best practices
Args = "diagnose" (e.g., "/integration-test diagnose OrderCommandIntegrationTests")
→ DIAGNOSE mode: analyze why tests fail — determine test bug vs code bug
Args = "verify" (e.g., "/integration-test verify {Service}")
→ VERIFY-TRACEABILITY mode: check test code matches specs and feature docs
Modes vs. flagged modes (name-collision note). The positional
reviewandverifyare lightweight positional branches, not the standalone--mode=review(deep quality) or--mode=verify(full verification) gates. In/integration-test → /integration-test --mode=review → /integration-test --mode=verify, invoke the flagged modes; use the positional branches for quick mid-generation passes.
Step 1: Find Targets
From-Changes Mode (default)
Run via Bash tool:
git diff --name-only; git diff --cached --name-only
Filter command/query files by project naming conventions (e.g., *Command.*, *Query.*). Use docs/project-config.json → modules or backendServices path patterns to derive service:
| Path pattern | Service | Test project |
|---|---|---|
Per docs/project-config.json service path pattern |
{Service} | {Service}.IntegrationTests (or project equivalent) |
Search for existing *.IntegrationTests.* projects to confirm mapping.
If no test project exists: inform user "No integration test project for {service}. See CLAUDE.md Integration Testing section to create one."
If test file already exists: ask user overwrite or skip.
From-Prompt Mode
User specifies command/query name. Use Grep (NOT bash grep):
Grep pattern="{CommandName}" path="{configured-source-root}" glob="{configured-source-glob}"
Step 2: Gather Context
For each target, read in parallel:
Use the project's actual equivalents below. An absent command/query layer, DI base or user-context factory is N/A; a native harness with fixtures remains a valid integration-test setup.
- Command/query file — extract: class name, result type, DTO properties, entity type
- Existing test files in same service — Glob
{Service}.IntegrationTests/**/*IntegrationTests.*, read ≥1 for conventions (collection/suite name, test annotations, namespace/imports, base class) - Service integration test base class — grep:
class.*ServiceIntegrationTestBase references/integration-test-patterns.md— canonical templates (adapt {Service} placeholders)
Step 2b: Look Up TC Codes (Strict TC Default Only)
For each target domain, read:
{App}/README.{Feature}.mdSection 8 under the business spec root (defaultdocs/specs; aspecRoots.business.pathentry indocs/project-config.jsonoverrides the path) — primary source
Build mapping: test-case description → TC code (e.g., "create valid order" → TC-OM-001).
- Uncovered business behavior with no TC → create it in Section 8 before generation. A technical-only contract regression uses the native
TechnicalSpeccarrier without manufacturing a business TC. - Outdated/incorrect TC → UPDATE IT first.
- Missing Section 8 → run
/spec [mode=tests]first.
Step 2c: Real-World Fidelity Check (BEFORE any test code is written)
MUST ATTENTION answer BEFORE the Arrange block exists — never after failure:
"Can this sequence, timing, and data actually occur in production?"
For each test, state:
- Sequence — can a real actor reach these steps in this order through the tested paths?
- Pacing — when actor timing belongs to the tested contract, preserve it; synchronous independent fixture cases need no artificial action delay.
- Data shape — can a real use-case path reach every seeded value (see direct-repository-write ban)?
- Barrier — for asynchronous steps, name and wait on the observable completion signal in ARRANGE. Synchronous outcomes use normal deterministic assertions.
Any "no" → fix the SCENARIO before writing; NEVER widen an assertion timeout afterward. Full contract: SYNC:real-world-fidelity-testing; barrier shape: references/integration-test-patterns.md → Pattern 10.
Test Architecture Contract Preflight (before Step 3)
Before writing code, complete and preserve this additive matrix; it does not replace real-DI, TC-traceability, async-polling, or Real-World Fidelity gates.
| Tier | Applicability + evidence | Owner | Runner/framework | Test root | Fixture/data strategy | Full command | Focused/partial command | Zero-match behavior | CI gate | Simple Windows/macOS/Linux entry point |
|---|---|---|---|---|---|---|---|---|---|---|
| Unit | APPLICABLE + {file:line} or N/A — {evidence} |
{owner} |
{configured runner/framework} |
{path} |
{strategy} |
{copy-ready command} |
{copy-ready command or N/A + evidence} |
{non-zero / configured behavior} |
{gate} |
{configured entry point or N/A + evidence} |
| Integration/System | APPLICABLE + {file:line} or N/A — {evidence} |
{owner} |
{configured runner/framework} |
{path} |
{strategy} |
{copy-ready command} |
{copy-ready command or N/A + evidence} |
{non-zero / configured behavior} |
{gate} |
{configured entry point or N/A + evidence} |
| E2E | APPLICABLE + {file:line} or N/A — {evidence} |
{owner} |
{configured runner/framework} |
{path} |
{strategy} |
{copy-ready command} |
{copy-ready command or N/A + evidence} |
{non-zero / configured behavior} |
{gate} |
{configured entry point or N/A + evidence} |
- Record unique run-identity source/format and business-data suffix before generation; carry both into the report. Mark
APPLICABLEonly with runner/framework/config evidence; otherwise recordN/A — <file:line evidence>and do not fabricate tests. - Verify every command from project config, reference docs, or runner script. If focused scope is supported, provide its command; otherwise record
N/Awith evidence. Invalid/zero-match selections must fail or use documented non-green behavior; zero matches never pass. - Record supported public-path setup, realistic valid data,
count-before-createidempotent reference setup, keyed/additive persistent data, and per-test/worker isolation. Shared mutable state is not run identity. - Matrix + run identity are required output evidence even for generate/review modes; execution results belong to
/integration-test --mode=verify.
Step 3: Generate Test File
File path: {project-test-dir}/{Service}.IntegrationTests/{Domain}/{CommandName}IntegrationTests{ext} (adapt path/extension per docs/project-config.json → integrationTestVerify.testProjectPattern)
Illustrative folder:
{Domain}is a domain grouping when that is the project’s convention. Preserve the actual native organization, including supported type-based layouts.
Structure: adapt layout, imports, fixtures, assertions, and markers from existing tests in the configured project.
namespace {Service}.IntegrationTests.{Domain};
[Collection({Service}IntegrationTestCollection.Name)]
[Trait("Category", "Command")] // or "Query"
public class {CommandName}IntegrationTests : {Service}ServiceIntegrationTestBase
{
// Select distinct behavior, failure and persistence cases from the protected contract
}
Test method naming: {CommandName}_When{Condition}_Should{Expectation}
Required patterns per command type:
| Command type | Required tests |
|---|---|
| Save/Create | Happy path + validation failure + DB state |
| Update | Create-then-update + verify updated fields in DB |
| Delete | Create-then-delete + AssertEntityDeletedAsync |
| Query | Filter returns results + pagination + empty result |
| Owns a universal hard rule or invariant in the selected profile (orthogonal to the rows above — applies to the same command/query) | + Pattern 9 property/metamorphic test plus boundary counter-case, tied to the profile's canonical invariant case. The strict default uses a §8 Invariant/Property TC; a native profile uses its declared identity/carrier. FORCED, not optional — a mutation of the invariant must fail an assertion. |
[FORCED BRANCH — property apparatus] Pattern 9 is not a "nice-to-have reference". For ANY command/query that enforces a universal hard rule or invariant in the selected profile, example-based rows are NOT sufficient — generate the Pattern 9 property test and boundary counter-case. The strict default maps these to
[HARD]§4 / §5 and its §8 property TC; a native profile uses its declared rule, case identity, and carrier. Skipping the property or boundary assertion leaves the invariant over-fitted to examples.
Review-bar alignment:
references/mode-review.mdGate 1 owns acceptance. Name the protected rule and a concrete behavioral break that makes its assertion fail. A per-line Mutation Probe Ledger or mutation tool is not universally required; choose useful strength evidence supported by the project. Preserve required broad-input invariant and boundary coverage under the selected profile.
Step 4: Verify
Build test project via project's build tool (see /integration-test --mode=verify for config-driven build).
Verify the applicable items below against the native runner and tested contract; state N/A for an absent capability rather than inventing it:
- Test collection/group attribute present with correct collection name
- Test category annotation present
- Shared mutable data has unique identities; isolated fixture values may be stable
- User context created via project's user context factory
- Persisted assertions use project helpers and polling only for asynchronous/eventually consistent contracts
- Use real production wiring at the integration boundary under test; test doubles are allowed only outside that boundary and must not replace the protected behavior
- Every test method has the traceability form required by the selected profile. The strict default uses
// TC-{FEATURE}-{NNN}: Descriptionplus its test-spec annotation.
Example Files to Study
Read references/integration-test-invocation-examples.md when Step 2 needs commands to find existing integration test files, base classes and fixtures, or when choosing the invocation for a case; it holds the find commands, the pattern-to-example table and the per-case invocation examples.
REVIEW Mode — Test Quality Audit
[BLOCKING] When positional review, read references/integration-test-skill-positional-review.md in full FIRST and follow that branch. The flagged --mode=review and --mode=verify retain their separate dispatch contracts.
DIAGNOSE Mode — Test Failure Root Cause Analysis
[BLOCKING] When positional diagnose, read references/integration-test-skill-positional-diagnose.md in full FIRST and follow that branch. The flagged --mode=review and --mode=verify retain their separate dispatch contracts.
VERIFY-TRACEABILITY Mode — Test ↔ Spec ↔ Feature Doc Verification
[BLOCKING] When positional verify, read references/integration-test-skill-positional-traceability.md in full FIRST and follow that branch. The flagged --mode=review and --mode=verify retain their separate dispatch contracts.
Test Data Setup Guidelines
| Pattern | When to Use | Example |
|---|---|---|
| Per-test inline | Simple tests, unique data | var order = new CreateOrderCommand { Name = UniqueName() } |
| Factory methods | Repeated entity creation | TestDataFactory.CreateValidOrder() |
| Builder pattern | Complex entities with many fields | new OrderBuilder().WithStatus(Active).WithItems(3).Build() |
| Shared fixture | Reference data needed by all tests | CollectionFixture.SeedReferenceData() |
Rules:
- Every test creates own data — no shared mutable state between tests
- Unique identifiers for shared mutable data (reuse project helpers); stable values are valid in isolated fixtures
- Factory methods return valid entities by default — tests override only what they test
- Cross-entity dependencies: create parent first, then child (e.g., User → Order)
- Feature requires reference/lookup data → set up in collection fixture or per-test preconditions
Test Execution & Failure Diagnosis (MANDATORY)
Verify-last exception (
SYNC:verify-last-order): when the caller's sequence has a LATER verify step — a parent workflow or plan that runs/integration-test --mode=verifyor/testafter its static review — this skill WRITES the tests and does NOT run them: that single verify, after the review, proves them (a fix step that amends a test does not run it either). One exception: characterization tests written BEFORE a refactor moves code are proven green on the unrefactored tree before it moves — insideworkflow-refactorby its one baseline run (this skill does not run them again), elsewhere by ONE targeted run. The rules below apply in full to a standalone call (no later verify step) and to the verify step itself.IMPORTANT MUST ATTENTION: After generating/modifying integration tests, when no later verify step exists, MUST:
- Run tests:
/integration-test --mode=verify(readsquickRunCommandfromdocs/project-config.json)- If tests fail: Diagnose root cause — (a) wrong test setup/assertions → fix test, or (b) service bug → report as finding
- NEVER mark done until tests pass. Unrun tests have zero value.
- Iterate: Fix → rerun → verify until all pass or failures confirmed as service bugs
Next Steps
Inside a workflow (THIS run is a step of a [Workflow] row: its own phase tasks are linked to that parent row, nested=true — a [Workflow] row that merely exists in TaskList, such as an abandoned one, does not count): skip the prompt below — the workflow's own next step is the next action. Otherwise (standalone, or only an unrelated [Workflow] row exists):
MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing, use ask user question tool to present:
- "/integration-test --mode=verify (Recommended)" — Run integration tests to verify they pass
- "/workflow-review-changes" — Review all changes before committing
- "Skip, continue manually" — user decides
Related Skills
Read references/integration-test-standalone-chain.md when deciding which neighbouring skill to call before or after this one; it holds the relationship table for /spec [mode=tests], /work-item --mode=review --type=spec-tests, /spec [mode=sync], /spec, /spec [mode=index], --mode=review, --mode=verify and /docs-manager --mode=update.
Standalone Chain
Read references/integration-test-standalone-chain.md when this skill is called outside a workflow, before finishing; it holds the standalone chain (Section 8 prerequisite, then the [REQUIRED] --mode=review → --mode=verify → /spec [mode=sync] steps and the recommended follow-ups) and the per-mode pre/post-step table.
[IMPORTANT]
TaskCreate— break ALL work into small tasks BEFORE starting. NEVER skip task creation.
Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.
core-engineering-principles— Core quality gate: easy to change, easy to scale, easy to maintain, judged by future change cost; planning, implementing or reviewing any change → .claude/skills/shared/protocols/core-engineering-principles.mdgraph-impact-analysis— Optional blast-radius query that suggests files a high-risk change may affect, a hint that can be stal
…(truncated)