
test-writing
- GitHub stars
- 47
Install
/plugin install test-writing@shopware-ai-coding-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add shopwareLabs/ai-coding-tools.
Contents
Discovered from sourceSkills 11
PHPUnit Integration Test Generation
Generate Shopware-compliant PHPUnit integration tests that exercise wired-up code through IntegrationTestBehaviour, produce integration-shape assertions, and pass PHPStan and PHPUnit validation.
File Write Restrictions
Write ONLY to:
tests/integration/**— Integration test files
NEVER write to:
src/**— Source code (read-only)tests/unit/**— Out of scope (usephpunit-unit-test-generation)tests/migration/**— Out of scope (usephpunit-migration-test-generation)- Any other directory
Workflow
digraph integration_test_generation {
"User invocation" [shape=doublecircle];
"Validate input" [shape=box];
"Source is PHP class in src/?" [shape=diamond];
"Analyze source" [shape=box];
"Integration pattern detected?" [shape=diamond];
"Select template + apply" [shape=box];
"Write test file" [shape=box];
"Validate (PHPStan, PHPUnit, ECS)" [shape=box];
"All green?" [shape=diamond];
"Fix iteration (max 3)" [shape=box];
"Iterations exhausted?" [shape=diamond];
"Report SUCCESS" [shape=doublecircle];
"Report PARTIAL" [shape=doublecircle];
"Report SKIPPED (defer to unit gen)" [shape=doublecircle];
"Report FAILED" [shape=doublecircle];
"User invocation" -> "Validate input";
"Validate input" -> "Source is PHP class in src/?";
"Source is PHP class in src/?" -> "Report FAILED" [label="no"];
"Source is PHP class in src/?" -> "Analyze source" [label="yes"];
"Analyze source" -> "Integration pattern detected?";
"Integration pattern detected?" -> "Report SKIPPED (defer to unit gen)" [label="no — unit-shape SUT"];
"Integration pattern detected?" -> "Select template + apply" [label="yes"];
"Select template + apply" -> "Write test file";
"Write test file" -> "Validate (PHPStan, PHPUnit, ECS)";
"Validate (PHPStan, PHPUnit, ECS)" -> "All green?";
"All green?" -> "Report SUCCESS" [label="yes"];
"All green?" -> "Iterations exhausted?" [label="no"];
"Iterations exhausted?" -> "Report PARTIAL" [label="yes"];
"Iterations exhausted?" -> "Fix iteration (max 3)" [label="no"];
"Fix iteration (max 3)" -> "Validate (PHPStan, PHPUnit, ECS)";
}
Phase 1: Validate Input
- Verify single file provided
- Verify file exists and is a PHP class (not interface/trait/abstract)
- Verify path starts with
src/
If validation fails, return FAILED with reason.
Phase 2: Analyze Source
Read the source class and detect which integration pattern applies. See references/source-analysis.md for the full detection logic.
Step 1: Extract Metadata
- Class name, full namespace
#[Package('...')]value for the test class — an integration test carries no#[CoversClass]target, so take the value from the nearestsrc/directory the test path mirrors, walking up until one exists and using the value its.phpfiles carry. When that yields no value, emit no#[Package]and report that in the Phase 5 report'sPackagefield (none, per references/output-format.md) rather than guessing a value.- Constructor dependencies (FQCN list)
- Area from namespace (
Core,Administration,Storefront,Elasticsearch) - Public methods and their return types
Step 2: Detect Pattern
Walk the decision table in references/source-analysis.md. Patterns are evaluated top to bottom; the first match wins.
| Pattern | Indicator |
|---|---|
controller | Extends AbstractController or AbstractRoute / Abstract*Route, or methods carry #[Route] |
scheduled-task | Extends ScheduledTaskHandler, OR has #[AsMessageHandler] and the __invoke() parameter is a ScheduledTask subclass |
message-handler | Has #[AsMessageHandler] on __invoke() AND the parameter is a domain message (not a ScheduledTask) |
indexer | Extends EntityIndexer (Shopware) |
dal-flow | Constructor takes EntityRepository AND public methods write through it (create, update, upsert) AND the SUT contract is "the data was persisted" or "the indexer/event was triggered" |
multi-service | Constructor takes ≥ 3 non-boundary dependencies (boundary set defined in INTEGRATION-002), and at least 2 are stateful (DAL, indexer, event dispatcher, system config) |
Step 3: Decide
- Pattern detected → Continue to Phase 3
- No pattern detected → The SUT is unit-shape. Return SKIPPED with
skip_type: unit_test_more_appropriateand reason: "Source class fits a unit-shape pattern (no persistence, no wiring, no multi-service coordination under test). Usephpunit-unit-test-generationinstead." Reference the relevant refactoring pattern inphpunit-integration-to-unit-migrating/references/refactoring-patterns.mdwhen the SUT looks like a factory, compiler pass, single subscriber, parser, constraint-only validator, or DAL materializer.
Phase 3: Generate Test
Step 1: Determine Test Path
Mirror source path with src/ → tests/integration/:
src/Core/Content/Product/ProductIndexer.php→tests/integration/Core/Content/Product/ProductIndexerTest.phpsrc/Core/Checkout/Cart/SalesChannel/CartLoadRoute.php→tests/integration/Core/Checkout/Cart/SalesChannel/CartLoadRouteTest.php
Namespace mirrors the path: Shopware\Tests\Integration\Core\Content\Product.
Step 2: Apply Template
Use the integration test template at templates/integration-test.md. The template has a base block plus one conditional section per pattern. Include exactly one pattern section based on Phase 2 detection. The base block defers all behavior trait use statements to the conditional section, because the trait choice varies by pattern:
- Always (base block): namespace,
#[Package],@internal, empty class shell — no#[CoversClass](integration tests carry none by convention) controller:IntegrationTestBehaviour + SalesChannelApiTestBehaviour(or admin/storefront equivalent),IdsCollection,KernelBrowserbuilt viacreateCustomSalesChannelBrowser([...]),#[Group('store-api')], request invocation, response assertionsscheduled-task:DatabaseTransactionBehaviour + KernelTestBehaviour(lighter thanIntegrationTestBehaviour),parent::setUp(), direct$handler->run()invocation, raw SQLConnection::fetchOne(...)assertionsmessage-handler:IntegrationTestBehaviour, direct($this->handler)($message)invocation, DAL read-back assertion (bus dispatch only when transport routing is part of the SUT contract)indexer:DatabaseTransactionBehaviour + KernelTestBehaviour,parent::setUp(), realtime flow — write via DAL captures$event,$indexer->update($event)returns?EntityIndexingMessage, assert on the returned message's datadal-flow:IntegrationTestBehaviour, arrange prerequisite state via DAL, invoke SUT, assert persisted result via separate DAL readmulti-service:IntegrationTestBehaviourcomposed with domain behaviours per dependency (AppSystemTestBehaviour,GuzzleTestClientBehaviour,MailTemplateTestBehaviour), configure inputs throughSystemConfigService/ DAL, invoke SUT, assert effects across multiple collaborators
Fill placeholders using Phase 2 metadata. Use IdsCollection (Shopware\Core\Test\Stub\Framework\IdsCollection) for any test that manages more than one entity ID, and type all repository properties with the generic PHPDoc @var EntityRepository<XxxCollection>. Leave TODO: markers where the behavior-specific arrange or assertion is genuinely SUT-dependent and not derivable from class structure — these are the spots a human or follow-up step must complete.
Step 3: Rule Compliance Checklist
The generated test must satisfy all INTEGRATION-001..008 rules at write time. Self-check before validation:
- INTEGRATION-001:
use IntegrationTestBehaviour;present - INTEGRATION-002: SUT and primary collaborators retrieved from container (not mocked); only boundary types may be mocked (HTTP client, mailer, clock, randomness)
- INTEGRATION-003: any DDL, filesystem write, or cache write has a matching teardown (or is wrapped in try/finally)
- INTEGRATION-004: assertions don't depend on wall-clock time or unsourced randomness — assertions on UUIDs go through referential lookups, not literal-value equality
- INTEGRATION-005: no
#[Depends]between test methods - INTEGRATION-006: never
markTestSkippedfor missing fixtures — create them - INTEGRATION-007: arrange + setUp keeps balance with assertion shape; if assertions are unit-shape only, switch to unit test generation (Phase 2 should have caught this)
- INTEGRATION-008: at least one assertion is integration-shape (persistence read-back, event observation, container resolution, HTTP response, real-broker delivery)
Step 4: Write Test File
Write to the path determined in Step 1.
Phase 4: Validate and Fix
Validation Loop
- [ ] PHPStan passes (0 errors)
- [ ] PHPUnit passes (all tests green)
- [ ] ECS passes (code style)
Step 1: Run PHPStan
{
"paths": ["tests/integration/Path/To/GeneratedTest.php"],
"error_format": "json"
}
Step 2: Fix PHPStan Errors
Common integration test errors:
- Missing imports for
IntegrationTestBehaviour,Context,Uuid,TestDefaults,Criteria - Type mismatches on
static::getContainer()->get(...)results — useassert($x instanceof Foo)or PHPDoc when the container returns the abstract type - Unknown method on
EntityRepository— verify the entity repository service id
Step 3: Run PHPUnit
{
"paths": ["tests/integration/Path/To/GeneratedTest.php"],
"output_format": "result-only"
}
If tests fail, re-run without output_format to get failure details.
Step 4: Fix Test Failures
Common integration test failures:
- DDL/filesystem state leaked from a previous run — add cleanup in
tearDown()(INTEGRATION-003) - Foreign-key constraint violations during DAL writes — set up required parent entities first
markTestSkippedtriggered by missing fixtures — replace with fixture creation (INTEGRATION-006)- Test references the wrong entity-repository service id
Step 5: Run ECS Check and Fix
Check for violations, then apply fixes if needed.
Repeat Until Pass
Loop Steps 1-5 until all validations pass. Maximum 3 iterations — after that, proceed to Phase 5 with status PARTIAL.
Phase 5: Generate Report
For output format and examples, see references/output-format.md.
Status Determination
| Condition | Status | skip_type |
|---|---|---|
| All validations pass | SUCCESS | — |
| Test generated, validation issues remain after 3 iterations | PARTIAL | — |
| Source class is unit-shape (no integration pattern matched) | SKIPPED | unit_test_more_appropriate |
| Invalid input (not a PHP class, file not found, not in src/) | FAILED | — |
PHPUnit Integration Test Review
Review a Shopware PHPUnit integration test for compliance with integration testing conventions.
Overview
Review the test against the composed integration catalog — INTEGRATION-001 through INTEGRATION-008 together with every convention, design, isolation, and provider rule whose test-types declares integration — assuming it belongs in tests/integration/. Do NOT load the placement reasoning rules (group: placement) and do NOT decide whether the test should be migrated.
Input
{test_path}(required unless{digest}is set, which supplies the class shape instead) — Path to the integration test file.{methods}(optional) — List of test method names to scope the review to. When omitted, the full class is reviewed.{review_unit}(optional) —method,class-structure,class-bodies, or a list of these. When set, only rules whose minimal evaluation unit matches load. When omitted, all rules load. Orthogonal to{methods}.{digest}(optional) — a pre-extracted, body-free structural digest of the test class. When set, review this text and skip reading the test file. Forcesclass-structurerules only. See Digest Mode.{rules}(optional) — the pre-rendered rule catalog as text, provided in your prompt. When set, enter Inline-Rules Mode: select rules from this text instead of callingget_rules. When omitted, rules load viaget_rules. See Inline-Rules Mode.{baseline}(optional) —pass,fail, orunavailable: this file's test state before the review, supplied by the caller. Defaults tounavailablewhen omitted. Record and report it; this skill never executes tests to obtain it.
Workflow
digraph integration_review {
"Review request" [shape=doublecircle];
"digest set?" [shape=diamond];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [shape=box];
"Phase 1: locate the file, verify tests/integration/, mirror the path onto src/ to identify the SUT, read the test file and its integration base" [shape=box];
"in tests/integration/?" [shape=diamond];
"STOP: FAILED - Not an integration test" [shape=octagon, style=filled, fillcolor=red];
"named methods resolve?" [shape=diamond];
"STOP: FAILED - No matching methods found" [shape=octagon, style=filled, fillcolor=red];
"src/ directory resolved by mirroring?" [shape=diamond];
"Phase 2: read the resolved src/ files, list their constructor dependencies, note the boundary interfaces INTEGRATION-002 allows mocking" [shape=box];
"Source resolution failed: continue with INTEGRATION-002 degraded - flag every non-boundary mock without the SUT-collaborator cross-check, and state in the report that source resolution failed and which rule it affected" [shape=box];
"Phase 3: build the rule filters - test_type=integration, no group, no test_category, scoped_review, review_unit" [shape=box];
"rules set?" [shape=diamond];
"Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" [shape=box];
"Call get_rules with the filters this mode sets" [shape=box];
"get_rules available?" [shape=diamond];
"STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [shape=octagon, style=filled, fillcolor=red];
"Phase 4: apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes; INTEGRATION-008 emits one informational hint per class and no further deliberation" [shape=box];
"Phase 5: apply the baseline - fail forces ISSUES_FOUND" [shape=box];
"Emit the report per references/output-format.md" [shape=doublecircle];
"Review request" -> "digest set?";
"digest set?" -> "Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [label="yes"];
"digest set?" -> "Phase 1: locate the file, verify tests/integration/, mirror the path onto src/ to identify the SUT, read the test file and its integration base" [label="no"];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" -> "rules set?";
"Phase 1: locate the file, verify tests/integration/, mirror the path onto src/ to identify the SUT, read the test file and its integration base" -> "in tests/integration/?";
"in tests/integration/?" -> "STOP: FAILED - Not an integration test" [label="no"];
"in tests/integration/?" -> "named methods resolve?" [label="yes"];
"named methods resolve?" -> "STOP: FAILED - No matching methods found" [label="none match"];
"named methods resolve?" -> "src/ directory resolved by mirroring?" [label="some or all match, or methods unset - each unmatched name is a warning"];
"src/ directory resolved by mirroring?" -> "Phase 2: read the resolved src/ files, list their constructor dependencies, note the boundary interfaces INTEGRATION-002 allows mocking" [label="yes"];
"src/ directory resolved by mirroring?" -> "Source resolution failed: continue with INTEGRATION-002 degraded - flag every non-boundary mock without the SUT-collaborator cross-check, and state in the report that source resolution failed and which rule it affected" [label="no - walked up to the src/ root"];
"Phase 2: read the resolved src/ files, list their constructor dependencies, note the boundary interfaces INTEGRATION-002 allows mocking" -> "Phase 3: build the rule filters - test_type=integration, no group, no test_category, scoped_review, review_unit";
"Source resolution failed: continue with INTEGRATION-002 degraded - flag every non-boundary mock without the SUT-collaborator cross-check, and state in the report that source resolution failed and which rule it affected" -> "Phase 3: build the rule filters - test_type=integration, no group, no test_category, scoped_review, review_unit";
"Phase 3: build the rule filters - test_type=integration, no group, no test_category, scoped_review, review_unit" -> "rules set?";
"rules set?" -> "Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" [label="yes"];
"rules set?" -> "Call get_rules with the filters this mode sets" [label="no"];
"Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" -> "Phase 4: apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes; INTEGRATION-008 emits one informational hint per class and no further deliberation";
"Call get_rules with the filters this mode sets" -> "get_rules available?";
"get_rules available?" -> "STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [label="no"];
"get_rules available?" -> "Phase 4: apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes; INTEGRATION-008 emits one informational hint per class and no further deliberation";
"Phase 4: apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes; INTEGRATION-008 emits one informational hint per class and no further deliberation" -> "Phase 5: apply the baseline - fail forces ISSUES_FOUND";
"Phase 5: apply the baseline - fail forces ISSUES_FOUND" -> "Emit the report per references/output-format.md";
}
Phase 1: Identify & Validate
- Locate test file (by path or
Glob("tests/integration/**/*Test.php")) - Verify file is in
tests/integration/(abort iftests/unit/ortests/migration/) - Identify the SUT by mirroring the test's directory onto
src/:tests/integration/X/Y/maps tosrc/X/Y/, walking up one directory level at a time until a directory exists undersrc/.#[CoversClass]is absent from integration tests by convention. - Read the full test file content
- Read any
use IntegrationTestBehaviour;/ base class to understand the lifecycle - If
{methods}provided: verify each named method exists. A method that is not found is a warning, and the remaining methods are still reviewed.
Phase 2: Source Analysis
- Read every
.phpfile directly inside thesrc/directory resolved by mirroring in Phase 1 step 3 — this is the resolved source set INTEGRATION-002 reads against. - List each source file's constructor dependencies. INTEGRATION-002 uses this list to distinguish primary collaborators from boundary collaborators.
- Note whether the SUT has explicit boundary interfaces (HTTP client, mailer, clock, randomness) — these are the allowable mock targets.
Phase 3: Rule Review Filters
All mcp__plugin_test-writing_test-rules__get_rules calls in Phase 4 carry test_type=integration and NO group — that composes the catalog for this test type. Adding group=integration narrows it back to the integration group alone and drops every shared rule.
When {methods} is provided, also add scoped_review=true. When {review_unit} is set, also add review_unit={value}; the filter is single-valued per call, so for a list (e.g. the fused whole-class track [class-structure, class-bodies]) issue one call per value and union the results. Never pass a test_category filter — A–E categories are a unit-review axis.
Do NOT call get_rules(group=placement). Placement reasoning is the migrating skill's responsibility.
Scoped Review Filtering (Phase 4)
When {methods} is provided, apply detection only to the named methods and their associated data providers (identified by #[DataProvider] attributes on scoped methods). The rest of the class is available for context, but violations outside the scoped methods are not reported.
Digest Mode
When {digest} is set, the supplied text is the only artifact under review:
- Do NOT
Readthe test file or the source class. The digest is body-free (class declaration,#[CoversClass], member order, method signatures, attribute lines, property declarations) and self-contained for class-structure rules. - Force
review_unit=class-structure. In Phase 4, callget_rules(test_type=integration, review_unit=class-structure)with NOscoped_review. Apply whatever rules the filter returns — the composed catalog's only class-structure rule is CONV-005. When{rules}is also set, instead select the class-structure rules from the inline text per Inline-Rules Mode (Review unit==class-structure). - Report
locationas a member name or attribute from the digest (line numbers are unavailable without the file body). {methods}and{review_unit}inputs are subsumed: the digest defines the scope and the unit.
Inline-Rules Mode
When {rules} is set, the catalog is provided as text in your prompt: select rules from that text instead of calling get_rules in Phase 4. Each rule in the text is a metadata header — # {id} — {title}, then Group: … | Enforce: …, then Test types: … | Categories: … | Scope: … | Review unit: … | Scoped review: … — followed by the rule body. The text is already the composed catalog for this test type, so every rule in it applies here: never filter on Group. Select a rule when ALL hold:
- if
{review_unit}is set: itsReview unitequals that value (for a list, take the union over the values), and - if
{methods}is set (scoped review): itsScoped reviewis notexclude.
Do not filter on Categories — A–E is a unit-review axis. Apply each selected rule's detection algorithm. While {rules} is set, the inline text is the complete rule set: NEVER read, open, search, or locate a rule file by any means — no Read/Grep/Glob, no get_rules. (Reading the test file and its source class is unaffected.) When {rules} is omitted, rules load via get_rules with the Phase 3 filters.
Phase 4: Apply Rules
For each rule obtained (inline selection or get_rules):
- Read the rule's Detection section
- Apply the detection logic against the test code (and source class when needed by INTEGRATION-002)
- Record violations with rule ID, title, enforce level, location, current code, and suggested fix
- For INTEGRATION-008 specifically: the rule produces a HINT, not an error or warning. Apply once per class, emit at most once in the Informational section. Do not deliberate further — the deep audit lives in the migrating skill.
Phase 5: Generate Report
Apply the pre-review baseline: when {baseline} is fail, the report opens with a line before ## Summary stating that this file's tests were already failing before this review, independent of the rule catalog below, and status becomes ISSUES_FOUND regardless of what the rule catalog finds. When {baseline} is unavailable, record it in the Summary's Baseline field and change nothing else. When {baseline} is pass, record it in the Summary's Baseline field.
For output format and examples, see references/output-format.md.
Report each issue using the rule's ID and title from mcp__plugin_test-writing_test-rules__get_rules:
### [{rule_id}] {title}
Include for each issue:
- Current Code — copied verbatim from the file at the cited location, read at review time. Never reconstructed from memory of the rule or paraphrased.
- Suggested Fix — the complete method body after the change. Empty only where the remediation deletes the method entirely;
deleted_methodsthen names that method. - Issue — names every line present in Current Code and absent from Suggested Fix. Each such line is a removal, and an unnamed removal is a defect in the finding. (The team-review schema names this field
summary.)
A suggested remediation never changes what an existing assertion pins, and never introduces an assertion as a means of satisfying a structural, layout, naming, or style constraint — a fix that must compensate that way is wrong by construction: do not emit it. Where the finding IS itself a missing test or a missing assertion (a coverage-gap rule such as INTEGRATION-007 or DESIGN-006), those new assertions are that finding's explicit deliverable: name them in the finding, and never smuggle them into a remediation for an unrelated rule. Deletions ride removed_assertions. Re-expressing the same pinned fact in a different call — CONV-012's assertTrue($a === $b) becoming assertSame($b, $a), or an ISOLATION-004 literal swap — does not change what the assertion pins.
Include the placement hint as a single line in the Informational section when INTEGRATION-008 fires.
Include full passed checks list.
Output Contract
test_path: tests/integration/Path/To/SomeTest.php
status: PASS|NEEDS_ATTENTION|ISSUES_FOUND|FAILED
baseline: pass | fail | unavailable # supplied by the caller; recorded and reported, never executed
errors:
- rule_id: INTEGRATION-001
title: "Integration test uses Shopware integration base"
enforce: must-fix
location: SomeTest.php:25
method: class-level # the test method the finding is in; "class-level" for a whole-class or structural finding
current: |
# problematic code
suggested: |
# fixed code
implies_src_change: false # true ONLY when the fix cannot be made in the test alone
deleted_methods: [] # test methods this fix removes ENTIRELY, by bare name; [] when it removes none
removed_assertions: [] # [{assertion, covered_by_test}] per assertion the fix removes
warnings:
- rule_id: INTEGRATION-007
title: "Setup-to-assertion ratio is balanced"
enforce: should-fix
location: SomeTest.php:60
method: testPersistsState
current: |
# code
suggested: |
# improved code
implies_src_change: false
deleted_methods: [testRedundantReadBack]
removed_assertions:
- assertion: "static::assertSame('active', $product->getState())"
covered_by_test: testPersistsState # the surviving test, or the literal "none — coverage lost"
informational:
- rule_id: INTEGRATION-008
title: "Placement smoke check"
method: class-level
hint: "Every assertion is unit-shape. Consider invoking phpunit-integration-to-unit-migrating on this file."
implies_src_change: false
deleted_methods: [] # an informational entry whose fix removes test code names it here too
removed_assertions: []
reason: null # the failure text when status is FAILED; null otherwise
Every entry names its method: the test method the finding is in, or the literal class-level for a whole-class or structural finding. method is half of a finding's identity (rule_id|method), so an omitted or empty value collapses every finding under one rule into the class-level bucket and merges defects that are not the same defect. Never leave it absent, and never write it with a trailing (...).
Set implies_src_change: true on a finding whose fix cannot be made in the test file alone — it requires a change under src/. Default it to false. It is informational: it never changes status and never turns a warning into an error.
Status Values
| Status | Condition |
|---|---|
| PASS | 0 errors, 0 warnings |
| NEEDS_ATTENTION | 0 errors, 1+ warnings |
| ISSUES_FOUND | 1+ errors |
| FAILED | Invalid input (file not found, not in tests/integration/), or a refusal from the deletion after-state check |
Informational entries never raise status — the INTEGRATION-008 placement hint and the guard's UNRESOLVED entry alike. PASS with a placement hint is still PASS. A fail {baseline} sets ISSUES_FOUND regardless of this table. A guard refusal sets FAILED regardless of this table and of the baseline — FAILED outranks every other status.
Track-Scoped Invocations
The team review decomposes large files into per-track reviews. Each track also receives {rules} (the pre-rendered catalog text in its prompt), so rule loading is Inline-Rules Mode selection rather than get_rules. Each track sets the inputs below:
- Method track —
test_path=…SomeTest.php,methods=[testCreate, testList],review_unit=method. Selects the catalog'smethodrules and judges only the named methods. - Fused whole-class track —
test_path=…,review_unit=[class-structure, class-bodies], plusmethods=[…]when the review is scoped. Reads full bodies; selects the class-structure and class-bodies rules from the inline text and unions them. - Class-structure digest —
digest="<class shape text>", notest_pathread. Per Digest Mode: select theclass-structurerules from the inline text and judge them against the digest.
Troubleshooting
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable:
- Report error: "test-rules MCP server not available — ensure the test-writing plugin is installed and Claude Code was restarted"
- Do not fall back to hardcoded checks
Not an Integration Test
If the file is not in tests/integration/:
- Report FAILED: "Not an integration test — this skill reviews tests in tests/integration/ only"
- Suggest
phpunit-unit-test-reviewingfortests/unit/andphpunit-migration-test-reviewingfortests/migration/
Source Directory Not Found
If directory mirroring walks up to the src/ root without finding an existing directory:
- Continue the review; INTEGRATION-002 falls back to flagging any non-boundary mock without the SUT-collaborator cross-check
- Note in the report that source resolution failed and which rule was affected
Placement vs. Review Boundary
The placement reasoning rules (group: placement, PLACEMENT-001..008) are NOT loaded by this skill. If the smoke check fires (INTEGRATION-008), the report emits a single hint; users must invoke phpunit-integration-to-unit-migrating explicitly to run the deliberation. Do not deliberate inline.
PHPUnit Integration-to-Unit Migration
Audits integration tests for misplacement and migrates the ones whose apparatus is not load-bearing.
When to use
- User explicitly asks to audit integration tests for migration candidates
- User points at a file/directory/PR and asks "should these be unit tests?"
- Following the placement smoke-alarm hint from
phpunit-integration-test-reviewing
This skill is adversarial about placement. It assumes integration tests are misplaced until proven otherwise. Do not invoke for general integration test review — use phpunit-integration-test-reviewing for that.
Workflow
digraph migration_audit {
"User invocation" [shape=doublecircle];
"Resolve scope" [shape=box];
"Per test: articulate SUT contract" [shape=box];
"Walk PLACEMENT-001..008" [shape=box];
"Veto from PLACEMENT-008?" [shape=diamond];
"Bucket: migrate" [shape=box];
"Bucket: split" [shape=box];
"Bucket: keep" [shape=box];
"Bucket: delete (duplicate)" [shape=box];
"Present buckets to user" [shape=box];
"User confirms migration set?" [shape=diamond];
"Execute migrations" [shape=box];
"Report" [shape=doublecircle];
"Stop (user declined)" [shape=octagon, style=filled, fillcolor=red];
"User invocation" -> "Resolve scope";
"Resolve scope" -> "Per test: articulate SUT contract";
"Per test: articulate SUT contract" -> "Walk PLACEMENT-001..008";
"Walk PLACEMENT-001..008" -> "Veto from PLACEMENT-008?";
"Veto from PLACEMENT-008?" -> "Bucket: keep" [label="yes (any veto)"];
"Veto from PLACEMENT-008?" -> "Bucket: migrate" [label="no, all unit-shape"];
"Veto from PLACEMENT-008?" -> "Bucket: split" [label="no, mixed"];
"Veto from PLACEMENT-008?" -> "Bucket: delete (duplicate)" [label="duplicate of unit coverage"];
"Bucket: migrate" -> "Present buckets to user";
"Bucket: split" -> "Present buckets to user";
"Bucket: keep" -> "Present buckets to user";
"Bucket: delete (duplicate)" -> "Present buckets to user";
"Present buckets to user" -> "User confirms migration set?";
"User confirms migration set?" -> "Execute migrations" [label="yes"];
"User confirms migration set?" -> "Stop (user declined)" [label="no"];
"Execute migrations" -> "Report";
}
Phase 1: Scope resolution
- Accept one of:
- Single test file path:
tests/integration/Core/.../SomeTest.php - Directory:
tests/integration/Core/Framework/App/Cms/ - Branch / PR / commit range: resolve to the list of integration test files touched
- Single test file path:
- List the integration test files in scope. If > 20, ask the user to narrow the scope or proceed in batches.
- Read each file's
#[CoversClass]and constructor of the SUT class(es) to ground later deliberation.
Phase 2: SUT contract articulation (REQUIRED gate)
For each test class in scope, before running any rule:
- Write down the SUT contract in one sentence, prefixed with "The SUT...":
OrderIndexerTest→ "The SUT rebuilds order line-item state from persisted product and discount data."DateFieldSerializerTest→ "The SUT serializes and deserializes date values via the field serializer's encode/decode methods."
- Classify the contract:
- Unit-shape (pure computation, decision, serialization, validation)
- Integration-shape (persistence, wiring, dispatch, multi-service interaction)
This step is not optional. Without an articulated contract, the rules below collapse into pattern matching on imports and produce false positives. Record the sentence in the bucket report.
Phase 3: Load placement rules
- Call
mcp__plugin_test-writing_test-rules__get_rules(group=placement)to load PLACEMENT-001..008 - Also call
mcp__plugin_test-writing_test-rules__get_rules(group=integration, test_type=integration)to have quality rules available — INTEGRATION-002 mock detection informs PLACEMENT-005's collaborator-graph reasoning, and INTEGRATION-008's assertion-shape catalog is referenced by PLACEMENT-004.
Phase 4: Apply placement rules
For each test method in each file:
- Run PLACEMENT-008 (stay-in-integration veto) first. If any veto indicator applies (persistence behavior under test, container wiring under test, HTTP layer, multi-service flow as SUT, migration/seed dependency, real broker, compiler-pass-under-kernel), record the veto and bucket the method as keep. Skip the remaining rules for that method.
- Otherwise, walk PLACEMENT-001 through PLACEMENT-007 in order. Record the verdict per rule with a brief justification (one sentence).
- Combine verdicts:
- All verdicts say "service locator / materializer / unit-shape / migrate" → bucket: migrate
- Verdicts are split (some methods migrate, some stay; or assertion shape is mixed) → bucket: split (move the migratable methods, keep the rest)
- Duplicate of existing unit coverage (detected via grep for the SUT in
tests/unit/) → bucket: delete (duplicate) — remove without re-creating; cross-reference existing unit test
Phase 5: Bucket report + user confirmation gate
Present the buckets to the user via the report format in references/output-format.md. Then call AskUserQuestion to confirm which buckets to execute:
- Confirm the
migrateset (default: all) - Confirm the
splitset (default: all) - Confirm the
deleteset (default: all) - The
keepset requires no action
Do NOT execute migrations without explicit user confirmation. If the user declines or wants to narrow, stop and report the audit only.
Phase 6: Execute migrations
For each test or method in the confirmed set, apply the appropriate refactoring pattern from references/refactoring-patterns.md:
- Container-fetched factory or service → construct explicitly with mocked DI collaborators
- CompilerPass → instantiate
ContainerBuilder, register definitions, call$pass->process($container), assert on definitions - Subscriber → instantiate, invoke handler directly with constructed event
- XML / JSON parser → move fixtures under
tests/unit/.../_fixtures/Resources/, drop kernel project dir - Constraint-only rule validation → instantiate
ValidatorviaValidation::createValidatorBuilder(), build the rule object, assert onConstraintViolationList - DAL materializer → construct entities in-memory with setters
For each migration:
- Create the new file under
tests/unit/...mirroring the source class's namespace - Apply the refactoring pattern
- Carry over data providers, test names, and assertions (assertions usually transfer unchanged)
- Add
#[Package('...')]carrying the unit-shape SUT's own value, then#[CoversClass(...)]matching that SUT (importShopware\Core\Framework\Log\Package). Where the SUT carries no#[Package], take the value from the nearestsrc/directory the test path mirrors; where that yields no value, add no#[Package]and record that against the created file in the Phase 7 report'sFiles Createdlist (none, per references/output-format.md) rather than guessing a value - Delete the migrated method (or the entire file, if all methods migrated) from the integration test
- If the integration class becomes empty, delete the file
For delete (duplicate) items: simply delete the integration test method/file and cross-reference the existing unit test in the report.
Phase 7: Report
Produce the final report per references/output-format.md: bucket summary, files created, files modified, files deleted, methods moved. Do NOT commit — leave the working tree dirty for the user to review.
Output Contract
scope:
type: file | directory | pr | branch
resolved_files: [tests/integration/...]
audit:
- file: tests/integration/Path/To/SomeTest.php
sut_contract: "The SUT..."
contract_shape: unit | integration | mixed
placement_verdicts:
PLACEMENT-001: service_locator | sut | n/a
PLACEMENT-002: materializer | dal_behavior | n/a
PLACEMENT-003: kernel_under_test | container_only | n/a
PLACEMENT-004: all_unit | mixed | majority_integration
PLACEMENT-005: r_count_0 | r_count_1 | r_count_2_plus
PLACEMENT-006: minimum_smaller | minimum_equal
PLACEMENT-007: name_body_coherent | name_misleading
PLACEMENT-008: veto_persistence | veto_wiring | veto_http | veto_multi_service | veto_migration | veto_broker | veto_compiler_pass | no_veto
bucket: migrate | split | keep | delete
veto_reason: null # filled when PLACEMENT-008 vetoes
execution:
files_created: [tests/unit/...]
files_modified: [tests/integration/...] # partial migrations
files_deleted: [tests/integration/...] # whole-class migrations or duplicates
methods_moved: 12
status: AUDITED | MIGRATED | DECLINED | FAILED
Status Values
| Status | Condition |
|---|---|
| AUDITED | Audit complete; user declined to migrate (or no migration candidates found) |
| MIGRATED | User confirmed and migrations executed |
| DECLINED | User declined to proceed after audit |
| FAILED | Invalid scope, source unreachable, or rules not loadable |
Troubleshooting
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable, abort with: "test-rules MCP server not available — ensure the test-writing plugin is installed and Claude Code was restarted." Do not attempt the audit from memory; the rules are the load-bearing reasoning prompts.
SUT Contract Unclear
If the SUT contract cannot be articulated in one sentence (the test does too many things, the #[CoversClass] is missing, the SUT is unclear), bucket the test as keep with reason "SUT contract unclear — refactor the test for clarity before considering migration." Do not migrate ambiguous tests.
Scope Too Large
If > 20 integration test files are in scope, ask the user via AskUserQuestion whether to narrow scope or proceed in batches. Batch by directory or #[CoversClass] namespace.
Refactoring Pattern Missing
If a test does not fit any of the patterns in references/refactoring-patterns.md but the rules say migrate, bucket as keep with reason "Migration would require a novel refactoring pattern not yet codified — consider keeping in integration and capturing the pattern as a follow-up."
After Migration
The skill does not run PHPUnit/PHPStan/ECS. After execution, the user (or a follow-up invocation of phpunit-unit-test-writing / phpunit-unit-test-reviewing) validates the migrated tests. Do not claim the migration is correct without that validation step.
PHPUnit Migration Test Generation
Generate Shopware-compliant PHPUnit migration tests that pass PHPStan and PHPUnit validation.
File Write Restrictions
Write ONLY to:
tests/migration/**— Migration test files
NEVER write to:
src/**— Source code (read-only)tests/unit/**— Unit tests (out of scope)tests/integration/**— Integration tests (out of scope)- Any other directory
Quick Start
- Read the target migration source class
- Analyze SQL operations to determine test pattern
- Apply the migration test template with conditional sections
- Validate with PHPStan and PHPUnit
- Fix any errors and repeat
- Generate completion report
Phase 1: Validate Input
- Verify single file provided
- Verify file exists and is a PHP class (not interface/trait)
- Verify path contains
Migration/V6_ - Verify class extends
Shopware\Core\Framework\Migration\MigrationStep
If validation fails, return FAILED with reason.
Phase 2: Analyze Source
Read the migration class and extract information needed for test generation. See references/source-analysis.md for detection patterns.
Step 1: Extract Metadata
- Class name, full namespace
- Timestamp from
getCreationTimestamp()return value #[Package('...')]attribute value — the test class carries the same value. When the migration class carries none, take the value from the nearestsrc/directory the test path mirrors, walking up until one exists and using the value its.phpfiles carry. When that yields no value, emit no#[Package]and report that in the Phase 5 report'sPackagefield (none, per references/output-format.md) rather than guessing a value.- Area from namespace (
Core,Administration,Storefront,Elasticsearch) - Version from namespace (
V6_6,V6_7,V6_8)
Step 2: Classify SQL Operations
Read update() and updateDestructive() method bodies. Classify:
- Schema-add: CREATE TABLE, addColumn(), ALTER TABLE ... ADD
- Schema-remove: DROP TABLE, DROP COLUMN, dropColumnIfExists(), dropTableIfExists()
- Data-update: UPDATE, INSERT, DELETE on non-config tables
- Config: system_config operations
- Mail-template: mail_template operations
A migration may contain multiple patterns (e.g., schema-add + data-update).
Step 3: Check updateDestructive
Determine if updateDestructive() has logic:
- Not overridden → no logic
- Empty body or only
parent::updateDestructive()→ no logic - Any other statement → has logic
Step 4: Select Traits
Based on detected patterns, select traits per references/source-analysis.md trait selection table.
Phase 3: Generate Test
Step 1: Determine Test Path
Mirror source path:
src/Core/Migration/V6_7/Migration1234Foo.php→tests/migration/Core/V6_7/Migration1234FooTest.phpsrc/Administration/Migration/V6_7/Migration1234Bar.php→tests/migration/Administration/V6_7/Migration1234BarTest.php
Step 2: Apply Template
Use the migration test template at templates/migration-test.md. Include conditional sections based on Phase 2 analysis:
- Always: base template, testGetCreationTimestamp, setUp with Connection
- Schema-add detected: rollback method, schema verification test
- updateDestructive has logic: updateDestructive test method
- Data-update detected: state setup, value assertion test
- Config detected: config insert/preserve tests
- Mail-template detected: minimal no-exception test
Fill all placeholders using Phase 2 metadata.
Step 3: Write Test File
Write to the path determined in Step 1.
Phase 4: Validate and Fix
Validation Loop
- [ ] PHPStan passes (0 errors)
- [ ] PHPUnit passes (all tests green)
- [ ] ECS passes (code style)
Step 1: Run PHPStan
{
"paths": ["tests/migration/Path/To/GeneratedTest.php"],
"error_format": "json"
}
Step 2: Fix PHPStan Errors
Common migration test errors:
- Missing imports for
TableHelper,KernelLifecycleManager,Uuid,Defaults - Type mismatches in assertion arguments
- Unknown method calls on
Connection
Step 3: Run PHPUnit
{
"paths": ["tests/migration/Path/To/GeneratedTest.php"],
"output_format": "result-only"
}
If tests fail, re-run without output_format to get failure details.
Step 4: Fix Test Failures
Common migration test failures:
- Column/table already exists (rollback not working)
- Wrong timestamp value
- Missing test data setup
- Transaction not rolling back (wrong trait)
Step 5: Run ECS Check and Fix
Check for violations, then apply fixes if needed.
Repeat Until Pass
Loop Steps 1-5 until all validations pass. Maximum 3 iterations — after that, proceed to Phase 5 with status PARTIAL.
Phase 5: Generate Report
For output format and examples, see references/output-format.md.
Status Determination
| Condition | Status |
|---|---|
| All validations pass | SUCCESS |
| Test generated, validation issues remain after 3 iterations | PARTIAL |
| Invalid input | FAILED |
PHPUnit Migration Test Review
Review a Shopware PHPUnit migration test for compliance with migration testing conventions.
Overview
Review the test against the composed migration catalog — MIGRATION-001..006, MIGRATION-008 and MIGRATION-009, all must-fix, together with every convention, design, isolation, and provider rule whose test-types declares migration, at whatever enforce level each carries.
Input
{test_path}(required unless{digest}is set, which supplies the class shape instead) — Path to the migration test file.{methods}(optional) — List of test method names to scope the review to. When omitted, the full class is reviewed.{review_unit}(optional) —method,class-structure,class-bodies, or a list of these. When set, only rules whose minimal evaluation unit matches load. When omitted, all rules load. Orthogonal to{methods}.{digest}(optional) — a pre-extracted, body-free structural digest of the test class. When set, review this text and skip reading the test file. Forcesclass-structurerules only. See Digest Mode.{rules}(optional) — the pre-rendered rule catalog as text, provided in your prompt. When set, enter Inline-Rules Mode: select rules from this text instead of callingget_rules. When omitted, rules load viaget_rules. See Inline-Rules Mode.{baseline}(optional) —pass,fail, orunavailable: this file's test state before the review, supplied by the caller. Defaults tounavailablewhen omitted. Record and report it; this skill never executes tests to obtain it.
Workflow
digraph migration_review {
"Review request" [shape=doublecircle];
"digest set?" [shape=diamond];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [shape=box];
"Phase 1: locate the file, verify tests/migration/, read CoversClass to find the source migration, verify it extends MigrationStep, read the test file" [shape=box];
"in tests/migration/, source class found and a MigrationStep?" [shape=diamond];
"STOP: FAILED - not a migration test, or source class missing or not a MigrationStep" [shape=octagon, style=filled, fillcolor=red];
"named methods resolve?" [shape=diamond];
"STOP: FAILED - No matching methods found" [shape=octagon, style=filled, fillcolor=red];
"Phase 2: read the source migration - decide whether updateDestructive has logic, list the SQL operations in update and updateDestructive, keep both for MIGRATION-002 and MIGRATION-004" [shape=box];
"Phase 3: build the rule filters - test_type=migration, no group, no test_category, scoped_review, review_unit" [shape=box];
"rules set?" [shape=diamond];
"Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" [shape=box];
"Call get_rules with the filters this mode sets" [shape=box];
"get_rules available?" [shape=diamond];
"STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [shape=octagon, style=filled, fillcolor=red];
"Phase 4: apply each rule's detection algorithm against the scoped code, feeding the Phase 2 source context to MIGRATION-002 and MIGRATION-004; record violations and write suggested fixes" [shape=box];
"Phase 5: apply the baseline - fail forces ISSUES_FOUND" [shape=box];
"Emit the report per references/output-format.md" [shape=doublecircle];
"Review request" -> "digest set?";
"digest set?" -> "Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [label="yes"];
"digest set?" -> "Phase 1: locate the file, verify tests/migration/, read CoversClass to find the source migration, verify it extends MigrationStep, read the test file" [label="no"];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" -> "rules set?";
"Phase 1: locate the file, verify tests/migration/, read CoversClass to find the source migration, verify it extends MigrationStep, read the test file" -> "in tests/migration/, source class found and a MigrationStep?";
"in tests/migration/, source class found and a MigrationStep?" -> "STOP: FAILED - not a migration test, or source class missing or not a MigrationStep" [label="no"];
"in tests/migration/, source class found and a MigrationStep?" -> "named methods resolve?" [label="yes"];
"named methods resolve?" -> "STOP: FAILED - No matching methods found" [label="none match"];
"named methods resolve?" -> "Phase 2: read the source migration - decide whether updateDestructive has logic, list the SQL operations in update and updateDestructive, keep both for MIGRATION-002 and MIGRATION-004" [label="some or all match, or methods unset - each unmatched name is a warning"];
"Phase 2: read the source migration - decide whether updateDestructive has logic, list the SQL operations in update and updateDestructive, keep both for MIGRATION-002 and MIGRATION-004" -> "Phase 3: build the rule filters - test_type=migration, no group, no test_category, scoped_review, review_unit";
"Phase 3: build the rule filters - test_type=migration, no group, no test_category, scoped_review, review_unit" -> "rules set?";
"rules set?" -> "Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" [label="yes"];
"rules set?" -> "Call get_rules with the filters this mode sets" [label="no"];
"Inline-Rules Mode: select from the inline composed catalog; never filter on Group or Categories; open no rule file" -> "Phase 4: apply each rule's detection algorithm against the scoped code, feeding the Phase 2 source context to MIGRATION-002 and MIGRATION-004; record violations and write suggested fixes";
"Call get_rules with the filters this mode sets" -> "get_rules available?";
"get_rules available?" -> "STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [label="no"];
"get_rules available?" -> "Phase 4: apply each rule's detection algorithm against the scoped code, feeding the Phase 2 source context to MIGRATION-002 and MIGRATION-004; record violations and write suggested fixes";
"Phase 4: apply each rule's detection algorithm against the scoped code, feeding the Phase 2 source context to MIGRATION-002 and MIGRATION-004; record violations and write suggested fixes" -> "Phase 5: apply the baseline - fail forces ISSUES_FOUND";
"Phase 5: apply the baseline - fail forces ISSUES_FOUND" -> "Emit the report per references/output-format.md";
}
Phase 1: Identify & Validate
- Locate test file (by path or
Glob("tests/migration/**/*Test.php")) - Verify file is in
tests/migration/directory (abort iftests/unit/ortests/integration/) - Read
#[CoversClass(...)]attribute to find the source migration class - Verify source class extends
Shopware\Core\Framework\Migration\MigrationStep - Read the full test file content
- If
{methods}provided: verify each named method exists. A method that is not found is a warning, and the remaining methods are still reviewed.
Phase 2: Source Analysis
- Read the source migration class identified by
#[CoversClass] - Determine if
updateDestructive()has logic:- Find the
updateDestructivemethod body - Empty body (
{},{ }) or onlyparent::updateDestructive($connection);= no logic - Any other statements = has logic
- Find the
- Identify SQL operations in
update()andupdateDestructive():- DDL:
CREATE TABLE,ALTER TABLE ... ADD,DROP TABLE,DROP COLUMN - DML:
INSERT,UPDATE,DELETE - system_config operations
- DDL:
- Store this context for rules that need it (MIGRATION-002, MIGRATION-004)
Phase 3: Rule Review Filters
All mcp__plugin_test-writing_test-rules__get_rules calls in Phase 4 carry test_type=migration and NO group — that composes the catalog for this test type. Adding group=migration narrows it back to the migration group alone and drops every shared rule.
When {methods} is provided, also add scoped_review=true. When {review_unit} is set, also add review_unit={value}; the filter is single-valued per call, so for a list (e.g. the fused whole-class track [class-structure, class-bodies]) issue one call per value and union the results. Never pass a test_category filter — A–E categories are a unit-review axis.
Scoped Review Filtering (Phase 4)
When {methods} is provided, apply detection only to the named methods and their associated data providers. The rest of the class is available for context, but violations outside the scoped methods are not reported.
Digest Mode
When {digest} is set, the supplied text is the only artifact under review:
- Do NOT
Readthe test file or the source class. The digest is body-free (class declaration,#[CoversClass], member order, method signatures, attribute lines, property declarations) and self-contained for class-structure rules. - Force
review_unit=class-structure. In Phase 4, callget_rules(test_type=migration, review_unit=class-structure)with NOscoped_review. Apply whatever rules the filter returns — the composed catalog's class-structure rules are CONV-005 and MIGRATION-008. When{rules}is also set, instead select the class-structure rules from the inline text per Inline-Rules Mode (Review unit==class-structure). - Report
locationas a member name or attribute from the digest (line numbers are unavailable without the file body). {methods}and{review_unit}inputs are subsumed: the digest defines the scope and the unit.
Inline-Rules Mode
When {rules} is set, the catalog is provided as text in your prompt: select rules from that text instead of calling get_rules in Phase 4. Each rule in the text is a metadata header — # {id} — {title}, then Group: … | Enforce: …, then Test types: … | Categories: … | Scope: … | Review unit: … | Scoped review: … — followed by the rule body. The text is already the composed catalog for this test type, so every rule in it applies here: never filter on Group. Select a rule when ALL hold:
- if
{review_unit}is set: itsReview unitequals that value (for a list, take the union over the values), and - if
{methods}is set (scoped review): itsScoped reviewis notexclude.
Do not filter on Categories — A–E is a unit-review axis. Apply each selected rule's detection algorithm. While {rules} is set, the inline text is the complete rule set: NEVER read, open, search, or locate a rule file by any means — no Read/Grep/Glob, no get_rules. (Reading the test file and its source class is unaffected.) When {rules} is omitted, rules load via get_rules with the Phase 3 filters.
Phase 4: Apply Rules
For each rule obtained (inline selection or get_rules):
- Read the rule's Detection / Detection Algorithm section
- Apply the detection logic against the test code
- For rules requiring source context (MIGRATION-002, MIGRATION-004), use Phase 2 results
- Record violations with rule ID, title, enforce level, location, current code, and suggested fix
Phase 5: Generate Report
Apply the pre-review baseline: when {baseline} is fail, the report opens with a line before ## Summary stating that this file's tests were already failing before this review, independent of the rule catalog below, and status becomes ISSUES_FOUND regardless of what the rule catalog finds. When {baseline} is unavailable, record it in the Summary's Baseline field and change nothing else. When {baseline} is pass, record it in the Summary's Baseline field.
For output format and examples, see references/output-format.md.
Report each issue using the rule's ID and title from mcp__plugin_test-writing_test-rules__get_rules:
### [{rule_id}] {title}
Include for each issue:
- Current Code — copied verbatim from the file at the cited location, read at review time. Never reconstructed from memory of the rule or paraphrased.
- Suggested Fix — the complete method body after the change. Empty only where the remediation deletes the method entirely;
deleted_methodsthen names that method. - Issue — names every line present in Current Code and absent from Suggested Fix. Each such line is a removal, and an unnamed removal is a defect in the finding. (The team-review schema names this field
summary.)
A suggested remediation never changes what an existing assertion pins, and never introduces an assertion as a means of satisfying a structural, layout, naming, or style constraint — a fix that must compensate that way is wrong by construction: do not emit it. Where the finding IS itself a missing test or a missing assertion (a coverage-gap rule such as MIGRATION-008 or DESIGN-006), those new assertions are that finding's explicit deliverable: name them in the finding, and never smuggle them into a remediation for an unrelated rule. Deletions ride removed_assertions. Re-expressing the same pinned fact in a different call — CONV-012's assertTrue($a === $b) becoming assertSame($b, $a), or an ISOLATION-004 literal swap — does not change what the assertion pins.
Include full passed checks list.
Output Contract
test_path: tests/migration/Path/To/MigrationTest.php
status: PASS|NEEDS_ATTENTION|ISSUES_FOUND|FAILED
baseline: pass | fail | unavailable # supplied by the caller; recorded and reported, never executed
errors:
- rule_id: MIGRATION-001
title: "Idempotency — update() called at least twice"
enforce: must-fix
location: MigrationTest.php:35
method: testMigration # the test method the finding is in; "class-level" for a whole-class or structural finding
current: |
# problematic code
suggested: |
# fixed code
implies_src_change: false # true ONLY when the fix cannot be made in the test alone
deleted_methods: [] # test methods this fix removes ENTIRELY, by bare name; [] when it removes none
removed_assertions: [] # [{assertion, covered_by_test}] per removed assertion; covered_by_test names the surviving test, or the literal "none — coverage lost"
warnings:
- rule_id: CONV-014
title: "Unclear AAA Structure"
enforce: should-fix
location: MigrationTest.php:60
method: testMigration
current: |
# code
suggested: |
# reordered code
implies_src_change: false
deleted_methods: [] # a CONV-014 fix reorders statements; it never deletes a method
removed_assertions: [] # nor an assertion — reordering must not change what any assertion pins
informational:
- rule_id: DESIGN-007
title: "Data Provider Consolidation"
enforce: consider
location: MigrationTest.php:80
method: class-level
suggestion: "Optional improvement"
implies_src_change: false
deleted_methods: [] # an informational entry whose fix removes test code names it here too
removed_assertions: []
reason: null # the failure text when status is FAILED; null otherwise
Every entry names its method: the test method the finding is in, or the literal class-level for a whole-class or structural finding. method is half of a finding's identity (rule_id|method), so an omitted or empty value collapses every finding under one rule into the class-level bucket and merges defects that are not the same defect. Never leave it absent, and never write it with a trailing (...).
Set implies_src_change: true on a finding whose fix cannot be made in the test file alone — it requires a change under src/ (for a migration test, the migration class itself). Default it to false. It is informational: it never changes status and never turns a warning into an error.
Status Values
| Status | Condition |
|---|---|
| PASS | 0 errors, 0 warnings |
| NEEDS_ATTENTION | 0 errors, 1+ warnings |
| ISSUES_FOUND | 1+ errors |
| FAILED | Invalid input (file not found, not in tests/migration/, source class missing or not a MigrationStep), or a refusal from the deletion after-state check |
MIGRATION-001..006, MIGRATION-008 and MIGRATION-009 are all must-fix; the composed catalog's should-fix rules (e.g. CONV-014) populate warnings, and its consider-level rules (e.g. CONV-005) populate informational. Informational entries never raise status — consider-level findings and the guard's UNRESOLVED entry alike. A fail {baseline} sets ISSUES_FOUND regardless of this table. A guard refusal sets FAILED regardless of this table and of the baseline — FAILED outranks every other status.
Track-Scoped Invocations
The team review decomposes large files into per-track reviews. Each track also receives {rules} (the pre-rendered catalog text in its prompt), so rule loading is Inline-Rules Mode selection rather than get_rules. Each track sets the inputs below:
- Method track —
test_path=…MigrationTest.php,methods=[testMigration, testMultipleExecutions],review_unit=method. Selects the catalog'smethodrules and judges only the named methods. - Fused whole-class track —
test_path=…,review_unit=[class-structure, class-bodies], plusmethods=[…]when scoped. Reads full bodies; selects the class-structure and class-bodies rules from the inline text and unions them. - Class-structure digest —
digest="<class shape text>", notest_pathread. Per Digest Mode: select theclass-structurerules from the inline text and judge them against the digest.
Troubleshooting
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable:
- Report error: "test-rules MCP server not available — ensure the test-writing plugin is installed and Claude Code was restarted"
- Do not fall back to hardcoded checks
Source Class Not Found
If the #[CoversClass] target cannot be located:
- Report FAILED: "Source migration class not found at expected path"
- Include the expected path based on namespace resolution
Not a Migration Test
If the file is not in tests/migration/:
- Report FAILED: "Not a migration test — this skill reviews tests in tests/migration/ only"
- Suggest using
phpunit-unit-test-reviewingfor unit tests
PHPUnit Adversarial Test Review
Stress-test reviewer consensus for any test type (unit, integration, or migration): form independent judgment before exposure to findings, then challenge weak consensus, resurrect premature withdrawals, and discover missed violations.
Input
{consensus}(required) — the consensus package:consensus_findings,withdrawn_findings, and the reconciliation record per file, provided in full in your prompt.{impressions}(optional) — impressions pre-formed in an earlier wave. When set, Phase 1 is already done and is skipped.{rules}(optional) — the pre-rendered rule catalog as text, provided in your prompt. When set, Phase 4 selects rules from it instead of callingget_rules.
Workflow
digraph adversarial_review {
"Adversarial review request" [shape=doublecircle];
"impressions supplied?" [shape=diamond];
"Phase 1: read each test file and its source class with no rules framework, apply every heuristic lens from references/intuitive-scan-guidance.md, record concerns with a severity estimate" [shape=box];
"test file and source class readable?" [shape=diamond];
"STOP: report the failure with the file path and the error; form no impressions, fabricate no files entry" [shape=octagon, style=filled, fillcolor=red];
"Phase 2: parse the consensus package, validate it carries consensus_findings, withdrawn_findings and a reconciliation record per file" [shape=box];
"Phase 3: contrast impressions against consensus per references/comparison-strategies.md - intuition-consensus gaps, weak consensus findings, premature withdrawals, unstated premises - into a prioritized candidate list" [shape=box];
"rules set?" [shape=diamond];
"Select the candidate's rules from the inline catalog by rule area; open no rule file" [shape=box];
"Call get_rules for the file's test_type, adding test_category only for unit tests" [shape=box];
"get_rules available?" [shape=diamond];
"STOP: report that the test-rules MCP server is unavailable; no candidate can be promoted without evidence, so emit a files entry with endorsements only and no promoted items, noting the limitation to the caller" [shape=octagon, style=filled, fillcolor=red];
"Phase 4: apply each detection algorithm against the actual code" [shape=box];
"does a detection algorithm substantiate the candidate?" [shape=diamond];
"Drop the candidate - intuition proposes, evidence disposes" [shape=box];
"Promote to a formal challenge, resurrection or new finding; endorse each consensus finding that Phase 1 independently confirmed and a detection algorithm supports" [shape=box];
"more than one file assigned?" [shape=diamond];
"Phase 5: compare rule treatment and shared patterns across the assigned files; promote a cross-file inconsistency only through the same evidence gate" [shape=box];
"Phase 6: group promoted items by file path, add endorsements and cross-file inconsistencies" [shape=box];
"Emit the challenges report per references/output-format.md" [shape=doublecircle];
"Adversarial review request" -> "impressions supplied?";
"impressions supplied?" -> "Phase 2: parse the consensus package, validate it carries consensus_findings, withdrawn_findings and a reconciliation record per file" [label="yes - Phase 1 already done"];
"impressions supplied?" -> "Phase 1: read each test file and its source class with no rules framework, apply every heuristic lens from references/intuitive-scan-guidance.md, record concerns with a severity estimate" [label="no"];
"Phase 1: read each test file and its source class with no rules framework, apply every heuristic lens from references/intuitive-scan-guidance.md, record concerns with a severity estimate" -> "test file and source class readable?";
"test file and source class readable?" -> "STOP: report the failure with the file path and the error; form no impressions, fabricate no files entry" [label="no"];
"test file and source class readable?" -> "Phase 2: parse the consensus package, validate it carries consensus_findings, withdrawn_findings and a reconciliation record per file" [label="yes"];
"Phase 2: parse the consensus package, validate it carries consensus_findings, withdrawn_findings and a reconciliation record per file" -> "Phase 3: contrast impressions against consensus per references/comparison-strategies.md - intuition-consensus gaps, weak consensus findings, premature withdrawals, unstated premises - into a prioritized candidate list";
"Phase 3: contrast impressions against consensus per references/comparison-strategies.md - intuition-consensus gaps, weak consensus findings, premature withdrawals, unstated premises - into a prioritized candidate list" -> "rules set?";
"rules set?" -> "Select the candidate's rules from the inline catalog by rule area; open no rule file" [label="yes"];
"rules set?" -> "Call get_rules for the file's test_type, adding test_category only for unit tests" [label="no"];
"Call get_rules for the file's test_type, adding test_category only for unit tests" -> "get_rules available?";
"get_rules available?" -> "STOP: report that the test-rules MCP server is unavailable; no candidate can be promoted without evidence, so emit a files entry with endorsements only and no promoted items, noting the limitation to the caller" [label="no"];
"get_rules available?" -> "Phase 4: apply each detection algorithm against the actual code" [label="yes"];
"Select the candidate's rules from the inline catalog by rule area; open no rule file" -> "Phase 4: apply each detection algorithm against the actual code";
"Phase 4: apply each detection algorithm against the actual code" -> "does a detection algorithm substantiate the candidate?";
"does a detection algorithm substantiate the candidate?" -> "Drop the candidate - intuition proposes, evidence disposes" [label="no"];
"does a detection algorithm substantiate the candidate?" -> "Promote to a formal challenge, resurrection or new finding; endorse each consensus finding that Phase 1 independently confirmed and a detection algorithm supports" [label="yes"];
"Drop the candidate - intuition proposes, evidence disposes" -> "more than one file assigned?";
"Promote to a formal challenge, resurrection or new finding; endorse each consensus finding that Phase 1 independently confirmed and a detection algorithm supports" -> "more than one file assigned?";
"more than one file assigned?" -> "Phase 5: compare rule treatment and shared patterns across the assigned files; promote a cross-file inconsistency only through the same evidence gate" [label="yes"];
"more than one file assigned?" -> "Phase 6: group promoted items by file path, add endorsements and cross-file inconsistencies" [label="no"];
"Phase 5: compare rule treatment and shared patterns across the assigned files; promote a cross-file inconsistency only through the same evidence gate" -> "Phase 6: group promoted items by file path, add endorsements and cross-file inconsistencies";
"Phase 6: group promoted items by file path, add endorsements and cross-file inconsistencies" -> "Emit the challenges report per references/output-format.md";
}
Phase 1: Independent Intuitive Scan
Read each assigned test file and its source class (from #[CoversClass]). Do NOT use MCP rule tools (get_rules) in this phase.
Load references/intuitive-scan-guidance.md for heuristic lenses, then for each file:
- Read the test file completely
- Read the source class under test (from
#[CoversClass]) - Apply each heuristic lens from the guidance
- Record concerns as free-form observations with severity estimate
Output per file:
impressions:
- file_path: tests/unit/Path/To/ClassTest.php
concerns:
- area: "brief description of concern"
severity: high | medium | low
Phase 2: Receive Consensus Package
Validate the package carries consensus_findings, withdrawn_findings, and reconciliation_record per file. This is the first exposure to reviewer reasoning — note your initial reactions before proceeding.
Phase 3: Structured Comparison
Load references/comparison-strategies.md. Per file, contrast impressions against consensus:
-
Intuition-consensus gaps — Phase 1 concerns that no reviewer raised. These are the highest-value candidates for new findings. For each unmatched concern, note which area of the code it targets.
-
Weak consensus findings — for each consensus finding, apply the "would this survive harder pushback?" test:
- MAJORITY findings with thin reasoning in the reconciliation record
- Findings where the reconciliation record shows quick concession without evidence
- Findings that don't match your Phase 1 impressions at all
-
Premature withdrawals — for each withdrawn finding, check:
- Does the concession reason cite a specific detection algorithm? If not, flag it.
- Did your Phase 1 scan independently flag the same area? If yes, strong resurrection candidate.
- Did only one reviewer push back while others followed? Bandwagon pattern.
-
Assumption excavation — for each consensus finding, state the unstated premise:
- What must be true for this finding to be valid?
- What breaks if that premise is wrong?
Output: prioritized list of candidate challenges, resurrections, and new findings — not yet evidence-backed.
Phase 4: Evidence Gathering
Per candidate, highest priority first:
- Load applicable rules and detection algorithms: when
{rules}is set, the inline text is the full rule catalog for this file's test type — select the rules relevant to the candidate finding and your lens axis. For unit tests, select those whoseCategoriesinclude the detected A–E category; integration and migration rules carryCategories: all, so select by rule area, not category. The text holds every rule, so NEVER read, open, search, or locate a rule file by any means (noRead/Grep/Glob, noget_rules); reading the test/source code is unaffected. Otherwise callmcp__plugin_test-writing_test-rules__get_rules(test_type={the file's test type}), addingtest_category={category}only for unit tests. - Apply the detection algorithm against the actual code
Promotion gate: promote a candidate to a formal challenge ONLY if a detection algorithm substantiates it. Drop candidates where the evidence doesn't hold up. This is the filter against contrarianism — intuition proposes, evidence disposes.
Endorsement: consensus findings that Phase 1 intuition independently confirmed AND that have strong detection algorithm support get endorsed. Endorsements are part of the output — they strengthen findings in the final report.
Phase 5: Cross-File Inconsistency Scan
Compare patterns across all assigned files:
-
For each rule_id that appears in any file's consensus, check if the same pattern exists in other files:
- File A's consensus accepted a pattern that file B's consensus flagged -> high-value challenge
- All files share the same weakness but none flagged it -> systemic finding
-
Compare treatment of similar code patterns:
- setUp() strategies across files
- Mocking approaches (createMock vs createStub)
- Assertion styles
- Data provider usage
Cross-file inconsistencies use the same promotion gate as Phase 4 — cite the detection algorithm.
Phase 6: Generate Challenges Report
Load references/output-format.md. Assemble the structured output: promoted challenges grouped by file path, every endorsement, and the Phase 5 cross-file inconsistencies.
The report carries no top-level status or failure-reason field — NO_CHALLENGES is simply a files entry with no challenges_to_consensus, resurrections, or cross_file_inconsistencies (endorsements only, or none). Failure to form impressions in Phase 1 is handled per Troubleshooting below, not by a status field here.
Output Contract
adversary: reviewer-2
files:
- path: tests/unit/Path/To/ClassTest.php
challenges_to_consensus:
- finding_id: "CONV-004|testFoo"
rule_id: CONV-004
consensus_was: UNANIMOUS | MAJORITY
challenge: "Detection algorithm requires X but..."
verdict_sought: overturn | weaken
resurrections:
- finding_id: "DESIGN-005|testBar"
rule_id: DESIGN-005
withdrawn_reason: "Conceded without evidence"
resurrection_argument: "The concession was premature because..."
code_evidence: "ClassTest.php:72 — ..."
new_findings:
- rule_id: ISOLATION-002
enforce: must-fix
location: ClassTest.php:88
method: testBaz
summary: "Description"
current: |
# code
suggested: |
# fix
implies_src_change: false # true ONLY when the fix cannot be made in the test alone
deleted_methods: [] # bare names of test methods this fix deletes outright
removed_assertions: [] # [{assertion, covered_by_test}] per assertion this fix drops
endorsements:
- rule_id: UNIT-003
reason: "Strong finding, correctly applied"
cross_file_inconsistencies:
- rule_id: CONV-004
this_file_status: accepted
other_file: tests/unit/Other/ClassTest.php
other_file_status: flagged
inconsistency: "Same pattern, divergent treatment"
finding_id on a challenge or resurrection is quoted verbatim from the consensus/withdrawn finding under scrutiny — never invented or altered. new_findings carries no detection_algorithm_citation field; cite the detection algorithm in summary instead.
Every new_findings entry carries implies_src_change, deleted_methods and removed_assertions — always, including when nothing applies (false, [], []). Set implies_src_change: true when the fix cannot be made in the test alone and requires a change under src/. Emit these fields whether or not a consensus package instructed you to: omitting them under-counts the source-change escalation and hides deletions from the after-state guard.
Troubleshooting
No Impressions Formed in Phase 1
If the test file or source class cannot be read:
- Stop and report the failure with the file path and error — do not proceed to comparison phases without impressions, and do not fabricate a
filesentry to fit the schema
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable:
- Report error: "test-rules MCP server not available — ensure the test-writing plugin is installed and Claude Code was restarted"
- Candidates from Phase 3 cannot be promoted without evidence — emit a
filesentry with no challenges, resurrections, or new_findings (endorsements only, if any), noting the limitation in the report handed back to the caller
All Candidates Fail Promotion Gate
If Phase 4 drops all candidates (none substantiated by detection algorithms):
- This is a valid outcome — emit a
filesentry with no challenges, resurrections, or new_findings - Include endorsements for strong consensus findings
- The adversary adds value by confirming the consensus is robust
PHPUnit Test Review Reconciling
Re-evaluate review findings against incoming critique and emit a binding revised stance, for any test type (unit, integration, or migration). Run in one of two modes: peer (reconcile against co-reviewers' findings) or adversary (reconcile against adversary challenges). Evidence — the rule's detection algorithm applied to the code — decides every disposition.
digraph reconcile {
"Reconcile request" [shape=doublecircle];
"mode?" [shape=diamond];
"peer: load own + peer findings on shared files" [shape=box];
"adversary: load own stance + adversary challenges" [shape=box];
"Per contested finding: load detection algorithm (inline RULES block by ID if rules set, else get_rules), apply to code" [shape=box];
"Evidence decides disposition — never social pressure" [shape=box];
"Emit binding revised stance" [shape=doublecircle];
"Reconcile request" -> "mode?";
"mode?" -> "peer: load own + peer findings on shared files" [label="peer"];
"mode?" -> "adversary: load own stance + adversary challenges" [label="adversary"];
"peer: load own + peer findings on shared files" -> "Per contested finding: load detection algorithm (inline RULES block by ID if rules set, else get_rules), apply to code";
"adversary: load own stance + adversary challenges" -> "Per contested finding: load detection algorithm (inline RULES block by ID if rules set, else get_rules), apply to code";
"Per contested finding: load detection algorithm (inline RULES block by ID if rules set, else get_rules), apply to code" -> "Evidence decides disposition — never social pressure";
"Evidence decides disposition — never social pressure" -> "Emit binding revised stance";
}
Input
The spawn prompt provides:
mode—peeroradversaryscopeper file — list of method names, orfull class. Reconcile only findings within the scoped methods; discard incoming items targeting out-of-scope code.{rules}(optional) — the pre-rendered rule catalog as text, provided in your prompt. When set, find contested rules by ID in that text; it holds every rule, so NEVER read, open, search, or locate a rule file by any means — noRead/Grep/Glob, noget_rules— not even to resolve a missing ID. Reading the cited code is unaffected. When omitted, rules load viaget_rules.
Mode peer additionally provides:
own_findings— your findings from the prior wave, per filepeer_findings— co-reviewers' findings on the same files, per file
Mode adversary additionally provides:
own_stance— your current binding stance, per fileadversary_challenges— challenges to consensus, resurrections, adversary-introduced findings, and endorsements, per file
Core Procedure
Load references/reconciliation-rules.md. Apply it to every disposition in both modes.
For each finding under contention:
- Load the detection algorithm: when
{rules}is set, find the rule by ID in that inline text; otherwise callmcp__plugin_test-writing_test-rules__get_rules(ids={rule_id}). - Apply the detection algorithm against the actual code at the cited location
- Decide the disposition on evidence alone (see mode sections below)
Mode: peer
Compare own findings against peer findings per file:
- Shared (you and a peer both reported) — endorse.
- Peer-only (peer reported, you did not) — challenge with a detection-algorithm citation, or concede. Do not add it to your own findings (no new findings in peer mode).
- Own-only (you reported, peer did not) — maintain with code evidence, or withdraw if a peer's challenge holds.
Output binding stance per file: findings you stand by, and withdrawn with reasons. See references/output-format.md.
Mode: adversary
Evaluate every adversary item per file:
- Challenge to consensus — defend with counter-evidence, or withdraw if the adversary's evidence holds.
- Resurrection of a finding withdrawn earlier — re-adopt if the adversary's evidence beats your original concession reason; otherwise maintain withdrawal with a strengthened reason.
- Adversary-introduced finding — challenge or concede by the same standard as a peer finding. Adopting it is allowed in adversary mode.
- Endorsement — no action.
Output binding stance per file with an adversary_impact tag on every entry: findings (defended | unchanged), re_adopted (resurrected), withdrawn (overturned), adopted_new (introduced). See references/output-format.md.
Troubleshooting
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable, detection algorithms cannot be verified.
- Mode
peer: concede peer findings you cannot verify; note the limitation in the stance. - Mode
adversary: maintain your current positions; note the limitation in the stance.
Team-Based PHPUnit Test Review
Resolve the input into a mixed test-file manifest, project the agent cost, partition the manifest into shards that each fit one workflow run, and drive the review as a campaign of sequential workflow launches with every stage result persisted to disk: a signals run (cross-file consistency + adoption), the review shards (consensus), a deterministic merge, and a gated adversarial run (red team + defense + arbitration). All stages launch the same committed workflow script, switched by a manifest mode. The review is strictly read-only — it never mutates the tests under review.
digraph team_review {
"Team review requested" [shape=doublecircle];
"Confirm scope + cost" [shape=diamond];
"Offer single-reviewer, stop" [shape=octagon, style=filled, fillcolor=red];
"Resolve input + classify each path (test_type)" [shape=box];
"File list empty?" [shape=diamond];
"Abort: no valid test files" [shape=octagon, style=filled, fillcolor=red];
"Fan out per-file extraction (parallel haiku subagents)" [shape=box];
"Resolve ambiguous entries (AskUserQuestion)" [shape=box];
"Verify method counts (workflow/verify-method-counts.sh)" [shape=box];
"Project agent cost (dry-run workflow) + select preset/models" [shape=box];
"Build shard plan (per-file weights, S_max)" [shape=box];
"Assemble campaign dir (campaign.json, args per shard + signals)" [shape=box];
"Launch signals run (mode=signals, background)" [shape=box];
"Launch next review shard (mode=review); persist result" [shape=box];
"Shard partial or failed?" [shape=diamond];
"Stop campaign: report completed shards + resume policy" [shape=octagon, style=filled, fillcolor=red];
"More shards?" [shape=diamond];
"Verify finding evidence per shard result (workflow/verify-finding-evidence.sh)" [shape=box];
"Merge: verdicts + coverage map + placement flags" [shape=box];
"Adversarial gate: run red team?" [shape=diamond];
"Launch adversarial run (mode=adversarial); persist result" [shape=box];
"Render combined report" [shape=doublecircle];
"Team review requested" -> "Confirm scope + cost";
"Confirm scope + cost" -> "Offer single-reviewer, stop" [label="declined"];
"Confirm scope + cost" -> "Resolve input + classify each path (test_type)" [label="proceed"];
"Resolve input + classify each path (test_type)" -> "File list empty?";
"File list empty?" -> "Abort: no valid test files" [label="yes"];
"File list empty?" -> "Fan out per-file extraction (parallel haiku subagents)" [label="no"];
"Fan out per-file extraction (parallel haiku subagents)" -> "Resolve ambiguous entries (AskUserQuestion)";
"Resolve ambiguous entries (AskUserQuestion)" -> "Verify method counts (workflow/verify-method-counts.sh)";
"Verify method counts (workflow/verify-method-counts.sh)" -> "Project agent cost (dry-run workflow) + select preset/models";
"Project agent cost (dry-run workflow) + select preset/models" -> "Build shard plan (per-file weights, S_max)";
"Build shard plan (per-file weights, S_max)" -> "Assemble campaign dir (campaign.json, args per shard + signals)";
"Assemble campaign dir (campaign.json, args per shard + signals)" -> "Launch signals run (mode=signals, background)";
"Launch signals run (mode=signals, background)" -> "Launch next review shard (mode=review); persist result";
"Launch next review shard (mode=review); persist result" -> "Shard partial or failed?";
"Shard partial or failed?" -> "Stop campaign: report completed shards + resume policy" [label="yes"];
"Shard partial or failed?" -> "More shards?" [label="no"];
"More shards?" -> "Launch next review shard (mode=review); persist result" [label="yes"];
"More shards?" -> "Verify finding evidence per shard result (workflow/verify-finding-evidence.sh)" [label="no"];
"Verify finding evidence per shard result (workflow/verify-finding-evidence.sh)" -> "Merge: verdicts + coverage map + placement flags";
"Merge: verdicts + coverage map + placement flags" -> "Adversarial gate: run red team?";
"Adversarial gate: run red team?" -> "Launch adversarial run (mode=adversarial); persist result" [label="run"];
"Adversarial gate: run red team?" -> "Render combined report" [label="skip"];
"Launch adversarial run (mode=adversarial); persist result" -> "Render combined report";
}
Phase 0: Confirm Scope & Cost
This review spawns many parallel agents and consumes substantially more tokens than a single-reviewer pass. Ask via AskUserQuestion whether to proceed with the team review or run a single-reviewer pass with the matching per-type reviewing skill (phpunit-unit-test-reviewing for unit, phpunit-integration-test-reviewing for integration, phpunit-migration-test-reviewing for migration) instead. Proceed only on confirmation. The preset and model combo are chosen later (Phase 2), informed by the projected agent count.
Phase 1: Resolve Input to a Manifest
Read references/input-resolution.md. Resolve the input to a file list and classify each path by its root — tests/unit/ → test_type=unit, tests/integration/ → integration, tests/migration/ → migration. Resolve interactive ambiguity that blocks resolution — base branch for a branch diff, unclear scope — with AskUserQuestion; the review cannot ask once it is running. If the file list is empty, abort per references/error-handling.md.
Then build each file's entry in parallel: spawn one general-purpose subagent per file, pinned to model: haiku, each running references/input-resolution.md §Per-File Extraction. Inline that contract verbatim into every spawn — a spawned agent never reads the reference. Each subagent measures its file with wc/grep (never estimates), enumerates every test method, resolves the #[CoversClass] source, computes the cross-file fingerprint and (when the file's combined lines exceed the digest threshold) the body-free digest — or, when the source cannot be resolved to a src/ file, returns ambiguous: true with a reason instead of guessing.
Aggregate the returned entries. For every entry flagged ambiguous, resolve it with AskUserQuestion and refill its fields from the answer — a guessed source size silently flips the track decision, so nothing ambiguous may reach the run. Let N = number of files.
Before the manifest freezes, Write the aggregated entries to a manifest-core JSON file and run ${CLAUDE_SKILL_DIR}/workflow/verify-method-counts.sh <manifest-core.json> <repo_root>; replace the manifest with its stdout. A subagent-reported method_count/test_methods mismatch is corrected to the extracted truth and logged to stderr — never merely a warning (references/input-resolution.md §Per-File Extraction). A missing entry file or invalid manifest JSON fails the script hard; treat it as an input-resolution failure (references/error-handling.md).
Output: a manifest of validated entries, each with test_type, method scope (methods, plus the diff-touched changed_methods on diff runs), the full test_methods list, resolved source_path/source_paths, decomposition measurements (test_lines, source_lines, method_count), fingerprint, a digest when combined lines exceed the threshold, and baseline (pass/fail/unavailable, supplied with the manifest — unavailable when not supplied; this skill does not execute tests to obtain it) (references/input-resolution.md).
Phase 2: Project the Cost, Select the Preset, Build the Shard Plan
Run the workflow in projection-only mode, let the user choose preset and model combo, then partition the manifest into shards that each fit one workflow run. This step spawns no review agents.
Writea dry-run input —{ "files": [<the Phase-1 entries>], "dry_run": true }— todry-args.json. A dry run needs no rule catalogs.- Build and launch it the same way Phase 4 launches a real run, but against
dry-args.json: run${CLAUDE_SKILL_DIR}/workflow/build-run-script.sh dry-args.json "$DRY_OUT"(withDRY_OUTamktemppath outside the repo), then theWorkflowtool withscriptPath: "$DRY_OUT"and noargs. It returns immediately with the projection result ({ dry_run: true, files, slots, model_combos, projections }— references/report-format.md §Dry-Run Projection). Each preset's projection carriesreview_agents_bound,adversarial_agents_bound, andper_fileshard weights. - Render
projectionsas a compact table (per preset:units,wave0_agents,review_agents_bound,adversarial_agents_bound), noting the bounds are upper bounds — conditional waves and capped arbitration run fewer. - Present preset + model combo as an
AskUserQuestion, defaulting tostandard/sonnet-opus.- preset —
deep/standard/lean: cost/quality operating point (whole-class coverage threshold, shard granularity, adversary lens count, arbitration caps). Per-preset values: references/reviewer-allocation.md. - models —
sonnet-opus/haiku-opus/haiku-sonnet: body and adversary model tiers. Lower body tiers cut cost but reduce rule-application precision; keep the adversary tier no lower than sonnet.
- preset —
- Build the shard plan from the chosen preset's
per_fileweights (references/reviewer-allocation.md §Shard Budget): if the preset'sreview_agents_bound≤ S_max (250), the plan is one shard; otherwise partition round-robin by descendingweightinto the fewest shards whose per-shard weight sums stay ≤ S_max. A file never straddles shards. Render the plan (shard count, files and projected agents per shard) with the projection table.
Phase 3: Assemble the Campaign on Disk
Each workflow run is sandboxed — no filesystem, no MCP — and reads its manifest from one inlined value. Assemble every stage's manifest as a JSON file inside one campaign directory; the catalogs are large (tens of KB each) by design, so splice them in by path and never load them into context.
-
Campaign directory. Create it outside the repository —
CAMPAIGN="$(mktemp -d)". Every args file, run-script, and stage result lives here; a later session resumes the campaign from this directory alone. -
Per-type rule catalogs. For each test type present in the manifest, call
build_rule_packageand keep the returned path (do notReadit). Each call composes that type's catalog — its own rule group plus every convention, design, isolation, and provider rule whosetest-typesdeclares the type — so never passgroup, which would narrow the catalog back to one group:- unit →
build_rule_package()(no arguments) - integration →
build_rule_package(test_type=integration) - migration →
build_rule_package(test_type=migration)
If a needed build fails or reports zero rules, abort (references/error-handling.md).
- unit →
-
Per-shard args. For each shard k,
Writeits Phase-1 entries (plus anybaseref and the Phase-2preset/modelsnames) to$CAMPAIGN/manifest-core-k.json, then merge the catalogs in by path withjq --rawfile— include only therule_packageskeys for types present in that shard:jq -n \ --slurpfile core "$CAMPAIGN/manifest-core-k.json" \ --rawfile unit <unit catalog path> \ --rawfile integ <integration catalog path> \ '{ mode: "review", files: $core[0].files, base: $core[0].base, preset: $core[0].preset, models: $core[0].models, rule_packages: { unit: $unit, integration: $integ } }' \ > "$CAMPAIGN/args-shard-k.json"Each entry's
baselinevalue carries through unchanged as part of$core[0].files— no separate wiring. -
Signals args.
Write{ "mode": "signals", "files": [<ALL Phase-1 entries>], "base": <base> }to$CAMPAIGN/args-signals.json— the signals run needs no rule catalogs. -
Campaign state.
Write$CAMPAIGN/campaign.json: the base ref, preset/models, and one entry per stage (signals,shard-1..N,adversarial) with its args path andstatus: "pending".
The manifests are fixed here, before any launch — nothing ambiguous may reach a run.
Phase 4: Execute the Campaign
Build each stage's run-script with ${CLAUDE_SKILL_DIR}/workflow/build-run-script.sh <args file> <out.mjs in $CAMPAIGN> and launch it with the Workflow tool (scriptPath, no args). The committed workflow/team-review.workflow.mjs is the sole orchestration for every stage — do not compose, write, or search for an alternative, and treat any leftover run-script from a prior run as stale. Launch directly: do not consult the advisor before launching.
- Launch the signals run first (it depends on nothing and runs concurrently with the first shard).
- Launch review shards strictly one at a time. Launch shard k; when its completion notification arrives,
Writethe raw result to$CAMPAIGN/shard-k.result.jsonand set itscampaign.jsonstatus before launching shard k+1. - Check every stage result before continuing. A result with
partial: true, a failed run, or a launch error stops the campaign: updatecampaign.json, report which stages completed and which did not, and apply the resume policy in references/error-handling.md — a storm-failed stage is relaunched clean; a circuit-breaker-halted stage may resume viaresumeFromRunId. Do not launch the next stage into a known-dead quota window. - When the signals result arrives,
Writeit to$CAMPAIGN/signals.result.json.
Phase 5: Merge the Consensus & Compute the Deterministic Signals
When all shards completed, merge on disk — no agents:
- Verify finding evidence. For every persisted
$CAMPAIGN/shard-k.result.json, run${CLAUDE_SKILL_DIR}/workflow/verify-finding-evidence.sh $CAMPAIGN/shard-k.result.json <repo_root>and overwrite the file with its stdout. A kept finding whosecurrentfails the evidence check is moved intocontested(tagged with anoutcomereason) and synced out of that file'sadversarial_input.kept— so a fabricated quote never reaches this merge, Phase 6'sargs-adversarial.json, or the report as kept. A referenced file missing on disk or an invalid result JSON fails the script hard; treat it as a stage result failure (references/error-handling.md). - Combined verdicts. Concatenate the (now evidence-checked) shard results'
filesarrays; aggregatekept_findings,contested_findings, andconcession_rate(weighted by each shard'swave0finding keys) from the shard summaries. - SUT-coverage map. Join every manifest entry's
source_pathsto its test path; report each SUT covered by ≥ 2 test files as{ sut, covered_by: [{path, test_type}], note }, notingintegration test redundant with existing unit coverage of this SUTwhen the covering set mixes unit and integration (references/report-format.md §Coverage Map). - Placement flags. Flag an integration file when (a) its merged result carries an
INTEGRATION-008informational finding, and/or (b) the coverage map shows it redundant with unit coverage. Each flag points atphpunit-integration-to-unit-migratingand never raises status.
Render the consensus-stage report section now (report-format.md) — it survives even if the adversarial stage never runs.
Phase 6: Adversarial Gate, Run & After-State Guard
The adversarial stage (red team + defense + arbitration) is the opus-priced part and the only stage that consumes consensus. Gate it explicitly, then check what the final finding set removes:
- Aggregate the shard summaries'
adversarial_gatesignals. If every shard recommends skip (zero kept findings, or concession ≥ 50%), recommend skipping. - Present the gate as an
AskUserQuestion: kept/contested totals, the skip signals, and the chosen preset'sadversarial_agents_boundfrom the Phase-2 projection. Default to run when findings exist and no skip signal fired. - On skip: the consensus-stage results are final; go to step 5.
- On run: assemble
$CAMPAIGN/args-adversarial.json—mode: "adversarial", ALL files, the samerule_packages/preset/models/base, plusconsensus: the array of every file'sadversarial_inputobject extracted from the shard results (jq, by path) — Phase 5 already ranverify-finding-evidence.shover these shard results, so a demoted finding is already out ofadversarial_input.keptbefore this extraction. Build, launch, persist to$CAMPAIGN/adversarial.result.jsonwith the same stop-on-partial policy as Phase 4.
Phase 7: Render the Report
Read references/report-format.md and render the combined report from the persisted stage results. The stage results carry fields only — every heading, label, and field line comes from that template. Render: per-file verdicts (the adversarial result's files supersede the consensus-stage entries for files it processed), the signals result's consistency and adoption_opportunities, the Phase-5 coverage map and placement flags, and the per-stage cost lines (each stage result's agents_spawned and output_tokens).
Each file's section states that file entry's baseline directly under its ## File: path heading — - **Baseline**: pass | fail | unavailable.
Every finding heading is exactly #### [RULE-ID] Title. Consensus, provenance (adversary_impact), branch scope (branch_touched), arbitration and source-change status are field lines under the heading, never heading suffixes; a finding carrying more than one suggested_variants entry renders each under its own numbered - **Suggested Fix** entry (report-format.md §Per-finding render conventions).
Every finding also carries a Scrutiny field line: adversary-tested when its file's findings passed through the adversarial stage's superseding verdicts, consensus-only otherwise — derived deterministically from which stage produced the file's final per-finding state, never asserted independently per finding (report-format.md §Per-finding render conventions).
This review has no fix phase — it only reports. For applying a report's remediations, Read references/fix-application.md.
Error Handling
For input-resolution failures, stage start-up or run failures, partial results (partial: true + halted_at), the campaign stop/resume policy, and consensus edge cases, Read references/error-handling.md.
PHPUnit Test Generation
Generate Shopware-compliant PHPUnit unit tests that pass PHPStan and PHPUnit validation.
File Write Restrictions
Write ONLY to:
tests/unit/**- Unit test files
NEVER write to:
src/**- Source code (read-only)tests/integration/**- Out of scope- Any other directory
Quick Start
- Read the target source class
- Check if test is required (see Phase 1)
- Determine test category (A-E)
- Apply the matching template
- Validate with PHPStan and PHPUnit
- Fix any errors and repeat
- Generate completion report
Phase 1: Analyze Source Class
Step 1: Check Coverage Exclusions
Before analyzing the source class, check if the project's phpunit.xml.dist (or phpunit.xml) excludes it from coverage. Files excluded from coverage do not need unit tests.
- Read
phpunit.xml.distfrom the project root - Find
<exclude>rules inside the<coverage>or<source>section - Match the source file path against each rule:
<directory suffix="X">path</directory>— excluded if file is underpathAND filename ends withX<file>path/to/File.php</file>— excluded if relative path matches exactly
- If excluded → Return SKIPPED with
skip_type: coverage_excludedand reason: "Source file excluded from coverage by phpunit.xml.dist (<matched-rule>)"
If phpunit.xml.dist is not found, skip this step.
Step 2: Determine If Test Is Required
Before generating any test, evaluate if the class/method requires one.
Quick check: Does the method body contain ONLY return <literal|constant|property|passthrough-new|delegation>?
- Yes -> NO TEST NEEDED — Return SKIPPED with
skip_type: no_logicand reason describing the pattern (e.g., "Pure accessor - no logic to test") - No (has conditionals/loops/transformations) -> Continue to Step 3
For detailed rules on what to test vs skip, see references/test-requirement-rules.md.
Step 3: Analyze Source Structure
Read the target class to determine:
- Public methods - What behaviors to test
- Constructor dependencies - What to mock/stub
- Return types - Expected outcomes
- Exception scenarios - Error paths (see references/exception-patterns.md)
- Deprecation markers -
@deprecatedtags,Feature::triggerDeprecationOrThrow(),Feature::silent(),Feature::callSilentIfInactive()(see references/deprecation-guards.md) - Package attribute - the
#[Package('...')]value the covered class carries. The test class carries the same value. When the covered class carries none, take the value from the nearestsrc/directory the test path mirrors, walking up until one exists and using the value its.phpfiles carry. When that yields no value, emit no#[Package]and report that in the Phase 5 report'sPackagefield (none, per references/output-format.md) rather than guessing a value.
Step 4: Detect Category
Use the decision tree to select the appropriate category:
Has constructor dependencies?
├── No → Is it an Exception class?
│ ├── Yes → Category E
│ └── No → Category A (DTO)
└── Yes → Uses EntityRepository?
├── Yes → Category D (DAL)
└── No → Implements EventSubscriberInterface or FlowAction?
├── Yes → Category C (Flow/Event)
└── No → Category B (Service)
For detailed category criteria, see references/category-detection.md.
Phase 2: Essential Rules
Apply these mandatory conventions when generating tests.
Quick Reference
| Rule | Requirement |
|---|---|
| File location | tests/unit/ mirroring src/ path |
| Class attributes | #[Package('...')] then #[CoversClass(TargetClass::class)], both required |
| Assertions | Use static:: not $this-> |
| Base class | Extend PHPUnit\Framework\TestCase |
| Method naming | test + Action + Condition + ExpectedResult |
| Attribute order | PHPDoc -> DataProvider -> TestDox -> method |
| One behavior | NO conditionals in tests |
TestDox Phrasing
TestDox MUST be a predicate phrase starting with an action verb:
- Good: "creates product", "returns null", "throws exception"
- Bad: "It creates...", "Should return...", "Tests that..."
Mocking Priority
- Real implementation - Use actual objects when simple
- Shopware stubs -
StaticEntityRepository,StaticSystemConfigService,Generator - PHPUnit mocks - Only for external/IO dependencies
For createStub vs createMock selection, see references/mocking-patterns.md.
For complete rules, see references/essential-rules.md.
Phase 3: Generate Test
Step 1: Select Template
Based on category from Phase 1:
| Category | Template |
|---|---|
| A (DTO) | templates/category-a-dto.md |
| B (Service) | templates/category-b-service.md |
| C (Flow/Event) | templates/category-c-flow.md |
| D (DAL) | templates/category-d-dal.md |
| E (Exception) | templates/category-e-exception.md |
For data provider and decoration contract patterns, see references/common-patterns.md.
Step 2: Replace Placeholders
{package}-#[Package]value from Phase 1 Step 3 (e.g.,framework,discovery){Module}- Core module (e.g.,Content,Checkout,System){Submodule}- Submodule path (e.g.,Product,Cart\LineItem){TargetClass}- Class name being tested{Entity}- Entity name for DAL tests{Method}- Method name being tested{Expected}- Expected outcome description{Condition}- Condition description{Exception}- Exception class name
Step 3: Write Test File
Write to correct location: tests/unit/{path matching src}/{ClassName}Test.php
Phase 4: Validate and Fix
Validation Loop
- [ ] PHPStan passes (0 errors)
- [ ] PHPUnit passes (all tests green)
- [ ] ECS passes (code style)
Step 1: Run PHPStan
{
"paths": ["tests/unit/Path/To/GeneratedTest.php"],
"error_format": "json"
}
Zero errors = pass.
Step 2: Fix PHPStan Errors
Apply fixes for common errors. See references/validation-error-mapping.md.
Step 3: Run PHPUnit
{
"paths": ["tests/unit/Path/To/GeneratedTest.php"],
"output_format": "result-only"
}
All tests passing = success. If tests fail, re-run without output_format to get failure details for Step 4.
Step 4: Fix Test Failures
Apply fixes for common failures. See references/validation-error-mapping.md.
Step 5: Run ECS Check and Fix
Check for violations, then apply fixes if needed.
Repeat Until Pass
Loop through Steps 1-5 until all validations pass.
Maximum iterations: Stop after 3 failed attempts and proceed to Phase 5.
Phase 5: Generate Report
For output format and examples, see references/output-format.md.
Status Determination
| Condition | Status | skip_type |
|---|---|---|
| All validations pass | SUCCESS | — |
| Test generated, validation issues remain after 3 iterations | PARTIAL | — |
| File excluded from coverage in phpunit.xml.dist | SKIPPED | coverage_excluded |
| No testable logic (per Test Requirement Rules) | SKIPPED | no_logic |
| Invalid input (not a PHP class, file not found) | FAILED | — |
Report Contents
- Summary: Source path, test path, status, category, package (or
nonewhen derivation yielded no value) - Generation Details: Test method count, template used
- Validation Results: PHPStan/PHPUnit/ECS pass/fail counts
- Remaining Issues (if PARTIAL): Location, error, status table
Additional Resources
Reference Files
For detailed patterns and techniques, consult:
- references/test-requirement-rules.md - Decision tree for what to test
- references/category-detection.md - How to categorize source classes
- references/essential-rules.md - Naming, attribute, structure rules
- references/validation-error-mapping.md - Error codes and fixes
- references/shopware-stubs.md - StaticEntityRepository, Generator patterns
- references/exception-patterns.md - expectExceptionObject, expectException + message, exception codes
- references/mocking-patterns.md - createStub vs createMock, intersection types, configuration, side-effect verification
- references/deprecation-guards.md - DisabledFeatures, skipTestIfActive/InActive, Feature::silent, class-level guards
- references/common-patterns.md - Data providers, AAA structure, event subscribers, decoration pattern
- references/output-format.md - Report output contract
Templates
Category-specific test generation templates in templates/:
- category-a-dto.md - Simple DTO/Entity tests
- category-b-service.md - Service tests with dependencies
- category-c-flow.md - Flow/Event subscriber tests
- category-d-dal.md - DAL/Repository tests
- category-e-exception.md - Exception handling tests
PHPUnit Unit Test Review
Review a Shopware PHPUnit unit test for compliance with testing guidelines and best practices.
Input
{test_path}(required unless{digest}is set, which supplies the class shape instead) — Path to the test file{methods}(optional) — List of test method names to scope the review to. When omitted, the full class is reviewed.{review_unit}(optional) —method,class-structure,class-bodies, or a list of these. When set, only rules whose minimal evaluation unit matches load. When omitted, all rules load. Orthogonal to{methods}: both may be set (e.g.methods=[...]+review_unit=method).{digest}(optional) — a pre-extracted, body-free structural digest of the test class. When set, review this text and skip reading the test file. Forcesclass-structurerules only. See Digest Mode.{rules}(optional) — the pre-rendered rule catalog as text, provided in your prompt. When set, enter Inline-Rules Mode: select rules from this text instead of callingget_rules. When omitted, rules load viaget_rules. See Inline-Rules Mode.{baseline}(optional) —pass,fail, orunavailable: this file's test state before the review, supplied by the caller. Defaults tounavailablewhen omitted. Record and report it; this skill never executes tests to obtain it.
Workflow
digraph unit_review {
"Review request" [shape=doublecircle];
"digest set?" [shape=diamond];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [shape=box];
"Phase 1: locate the file, verify tests/unit/, check CoversClass, detect category A-E, verify class structure and base class, count test methods, read the source class" [shape=box];
"a unit test class in tests/unit/?" [shape=diamond];
"STOP: FAILED - not a unit test, or not a test class" [shape=octagon, style=filled, fillcolor=red];
"unit and integration patterns mixed in one class?" [shape=diamond];
"STOP: abort - Mixed test types detected, review unit test portions only" [shape=octagon, style=filled, fillcolor=red];
"named methods resolve?" [shape=diamond];
"STOP: FAILED - No matching methods found" [shape=octagon, style=filled, fillcolor=red];
"Phase 2: build the rule filters - test_type=unit, test_category, scoped_review, review_unit" [shape=box];
"rules set?" [shape=diamond];
"Inline-Rules Mode: select from the inline catalog by the filter predicate; open no rule file" [shape=box];
"Call get_rules per group with the filters this mode sets" [shape=box];
"get_rules available?" [shape=diamond];
"STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [shape=octagon, style=filled, fillcolor=red];
"Phases 3-7: per group, apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes" [shape=box];
"Phase 8: apply the baseline - fail forces ISSUES_FOUND" [shape=box];
"Emit the report per references/output-format.md" [shape=doublecircle];
"Review request" -> "digest set?";
"digest set?" -> "Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" [label="yes"];
"digest set?" -> "Phase 1: locate the file, verify tests/unit/, check CoversClass, detect category A-E, verify class structure and base class, count test methods, read the source class" [label="no"];
"Digest Mode: judge the digest text alone; force class-structure rules; read nothing from disk" -> "rules set?";
"Phase 1: locate the file, verify tests/unit/, check CoversClass, detect category A-E, verify class structure and base class, count test methods, read the source class" -> "a unit test class in tests/unit/?";
"a unit test class in tests/unit/?" -> "STOP: FAILED - not a unit test, or not a test class" [label="no"];
"a unit test class in tests/unit/?" -> "unit and integration patterns mixed in one class?" [label="yes"];
"unit and integration patterns mixed in one class?" -> "STOP: abort - Mixed test types detected, review unit test portions only" [label="yes"];
"unit and integration patterns mixed in one class?" -> "named methods resolve?" [label="no"];
"named methods resolve?" -> "STOP: FAILED - No matching methods found" [label="none match"];
"named methods resolve?" -> "Phase 2: build the rule filters - test_type=unit, test_category, scoped_review, review_unit" [label="some or all match, or methods unset - each unmatched name is a warning"];
"Phase 2: build the rule filters - test_type=unit, test_category, scoped_review, review_unit" -> "rules set?";
"rules set?" -> "Inline-Rules Mode: select from the inline catalog by the filter predicate; open no rule file" [label="yes"];
"rules set?" -> "Call get_rules per group with the filters this mode sets" [label="no"];
"Inline-Rules Mode: select from the inline catalog by the filter predicate; open no rule file" -> "Phases 3-7: per group, apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes";
"Call get_rules per group with the filters this mode sets" -> "get_rules available?";
"get_rules available?" -> "STOP: FAILED - test-rules MCP server not available; never fall back to hardcoded checks" [label="no"];
"get_rules available?" -> "Phases 3-7: per group, apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes";
"Phases 3-7: per group, apply each rule's detection algorithm against the scoped code, record violations, write suggested fixes" -> "Phase 8: apply the baseline - fail forces ISSUES_FOUND";
"Phase 8: apply the baseline - fail forces ISSUES_FOUND" -> "Emit the report per references/output-format.md";
}
Phase 1. Identify & Classify
- Locate test file (by path or
Glob("tests/unit/**/*Test.php")) - Verify in
tests/unit/directory (abort iftests/integration/) - Check CoversClass covers exactly one class
- Determine test category (A-E) per references/test-categories.md
- Verify class structure order
- Verify extends
TestCaseor appropriate base class - Count test methods (data providers, TestDox, conditionals)
- Read source class under test (from
#[CoversClass]) — needed by rules that analyze test-to-code-path coverage - If
{methods}provided: verify each named method exists in the test class. A method that is not found is a warning, and the remaining methods are still reviewed.
Phase 2. Rule Review Filters
All mcp__plugin_test-writing_test-rules__get_rules calls in Phases 3-7 include these shared filters: test_type=unit, test_category={detected_category}, scoped_review={true if methods provided, omit otherwise}.
When {review_unit} is set, also add review_unit={value} to every call. The review_unit filter is single-valued per call: for a list (e.g. the fused whole-class track [class-structure, class-bodies]), issue one get_rules call per value and union the results within each group. When {review_unit} is omitted, leave the filter off (all rules load).
Scoped Review Filtering (Phases 3-7)
When {methods} is provided, apply this constraint to ALL rule detection in Phases 3-7:
- Apply detection logic only to the named methods and their associated data providers (identified by
#[DataProvider]attributes on scoped methods) - Skip methods not in the scope
- The rest of the class is available for context (e.g., checking if a data provider is shared, understanding import statements) but violations outside the scoped methods are not reported
Digest Mode
When {digest} is set, the supplied text is the only artifact under review:
- Do NOT
Readthe test file or the source class. Detect nothing from disk; the digest is body-free (class declaration,#[CoversClass], member order, method signatures, attribute lines, property declarations) and self-contained for class-structure rules. - Force
review_unit=class-structure. In Phases 3-7, callget_rules(group={group}, review_unit=class-structure)with NOtest_categoryand NOscoped_review. Apply whatever rules the filter returns — class-structure rules are category-agnostic, and groups with none return nothing. When{rules}is also set, instead select the class-structure rules from the inline text per Inline-Rules Mode (group match +Review unit==class-structure, no category and no scoped filter). - Report
locationas a member name or attribute from the digest (line numbers are unavailable without the file body). {methods}and{review_unit}inputs are subsumed: the digest defines the scope and the unit.
Inline-Rules Mode
When {rules} is set, the catalog is provided as text in your prompt: select rules from that text instead of calling get_rules in Phases 3-7. Each rule in the text is a metadata header — # {id} — {title}, then Group: … | Enforce: …, then Test types: … | Categories: … | Scope: … | Review unit: … | Scoped review: … — followed by the rule body. Per phase, select a rule when ALL hold:
- its
Groupequals the current phase's group, and - the detected category is in its
CategoriesCSV, and - if
{review_unit}is set: itsReview unitequals that value (for a list, take the union over the values), and - if
{methods}is set (scoped review): itsScoped reviewis notexclude.
Apply each selected rule's detection algorithm exactly as in Phases 3-7. While {rules} is set, the inline text is the complete rule set: NEVER read, open, search, or locate a rule file by any means — no Read/Grep/Glob, no get_rules — not to resolve a rule ID, fetch a detection algorithm, or check for missing content. (Reading the test file and its source class is unaffected — that is required.) When {rules} is omitted, rules load via get_rules with the Phase 2 filters.
Phases 3-7. Review Rules by Group
For each group in the table below:
- Obtain the group's rules: when
{rules}is set, select them from the inline text per Inline-Rules Mode; otherwise callmcp__plugin_test-writing_test-rules__get_rules(group={group})with the Phase 2 filters. - For each rule: a. Read the rule's Detection/Detection Algorithm sections b. Apply the detection logic against the test code (and source class when marked below) c. If the rule cross-references other rules, follow the cross-reference d. Record violations with the rule's ID, title, and enforce level
- Generate suggested fixes following each rule's Fix section
| Phase | Group | Covers | + Source class |
|---|---|---|---|
| 3 | convention | Naming, attributes, TestDox, assertions, class structure, method ordering | |
| 4 | design | Conditionals, single behavior, test redundancy, data provider usage, coverage distribution | ✓ |
| 5 | unit | Behavior vs implementation focus, mocking strategy, call-count coupling | ✓ |
| 6 | isolation | FIRST principles (Independent, Repeatable), shared state, fixtures, feature flags | |
| 7 | provider | Data provider key quality, naming, yield patterns, TestDox parameters |
Phase 8. Generate Report
Apply the pre-review baseline: when {baseline} is fail, the report opens with a line before ## Summary stating that this file's tests were already failing before this review, independent of the rule catalog below, and status becomes ISSUES_FOUND regardless of what the rule catalog finds. When {baseline} is unavailable, record it in the Summary's Baseline field and change nothing else. When {baseline} is pass, record it in the Summary's Baseline field.
For output format and examples, see references/output-format.md.
Report each issue using the rule's ID and title from mcp__plugin_test-writing_test-rules__get_rules:
### [{rule_id}] {title}
Include for each issue:
- Current Code — copied verbatim from the file at the cited location, read at review time. Never reconstructed from memory of the rule or paraphrased.
- Suggested Fix — the complete method body after the change. Empty only where the remediation deletes the method entirely;
deleted_methodsthen names that method. - Issue — names every line present in Current Code and absent from Suggested Fix. Each such line is a removal, and an unnamed removal is a defect in the finding. (The team-review schema names this field
summary.)
A suggested remediation never changes what an existing assertion pins, and never introduces an assertion as a means of satisfying a structural, layout, naming, or style constraint — a fix that must compensate that way is wrong by construction: do not emit it. Where the finding IS itself a missing test or a missing assertion (a coverage-gap rule such as DESIGN-006), those new assertions are that finding's explicit deliverable: name them in the finding, and never smuggle them into a remediation for an unrelated rule. Deletions ride removed_assertions. Re-expressing the same pinned fact in a different call — CONV-012's assertTrue($a === $b) becoming assertSame($b, $a), or an ISOLATION-004 literal swap — does not change what the assertion pins.
Include full passed checks list.
Output Contract
test_path: tests/unit/Path/To/ClassTest.php
status: PASS|NEEDS_ATTENTION|ISSUES_FOUND|FAILED
baseline: pass | fail | unavailable # supplied by the caller; recorded and reported, never executed
scope:
mode: scoped | full
methods: [method1, method2] # only when mode=scoped
errors:
- rule_id: {from mcp__plugin_test-writing_test-rules__get_rules response}
title: {from mcp__plugin_test-writing_test-rules__get_rules response}
enforce: must-fix
location: ClassTest.php:45
method: testValidatesTotalAgainstThreshold # the test method the finding is in; "class-level" for a whole-class or structural finding
current: |
# problematic code
suggested: |
# fixed code
implies_src_change: false # true ONLY when the fix cannot be made in the test alone
deleted_methods: [] # test methods this fix removes ENTIRELY, by bare name; [] when it removes none
removed_assertions: [] # [{assertion, covered_by_test}] per assertion the fix removes
warnings:
- rule_id: {from mcp__plugin_test-writing_test-rules__get_rules response}
title: {from mcp__plugin_test-writing_test-rules__get_rules response}
enforce: should-fix
location: ClassTest.php:78
method: testCountsItems
current: |
# code
suggested: |
# improved code
implies_src_change: false
deleted_methods: [testRedundantEmptyCase]
removed_assertions:
- assertion: "static::assertSame(3, $result->count())"
covered_by_test: testCountsItems # the surviving test, or the literal "none — coverage lost"
informational:
- rule_id: {from mcp__plugin_test-writing_test-rules__get_rules response}
title: {from mcp__plugin_test-writing_test-rules__get_rules response}
enforce: consider
location: ClassTest.php:96
method: class-level
suggestion: "Optional improvement"
implies_src_change: false
deleted_methods: [] # an informational entry whose fix removes test code names it here too
removed_assertions: []
reason: null # the failure text when status is FAILED; null otherwise
Every entry names its method: the test method the finding is in, or the literal class-level for a whole-class or structural finding. method is half of a finding's identity (rule_id|method), so an omitted or empty value collapses every finding under one rule into the class-level bucket and merges defects that are not the same defect. Never leave it absent, and never write it with a trailing (...).
Set implies_src_change: true on a finding whose fix cannot be made in the test file alone — it requires a change under src/. Default it to false. It is informational: it never changes status and never turns a warning into an error.
Informational entries never raise status. PASS with an informational entry is still PASS.
Troubleshooting
Ambiguous Category Detection
When test characteristics match multiple categories:
- Check primary class under test via
#[CoversClass] - Use most restrictive category (D > C > B > A)
- Exception tests (E) take precedence when
expectExceptionpresent
Mixed Test Types
When a test class contains both unit and integration patterns:
- Abort with message: "Mixed test types detected - review unit test portions only"
- Flag the applicable rule if the test covers multiple classes
MCP Tool Unavailability
If mcp__plugin_test-writing_test-rules__get_rules is unavailable:
- Report error: "test-rules MCP server not available — ensure the test-writing plugin is installed and Claude Code was restarted"
- Do not fall back to hardcoded checks
Status Values
| Status | Condition |
|---|---|
| PASS | 0 errors, 0 warnings (informational entries do not change status) |
| NEEDS_ATTENTION | 0 errors, 1+ warnings |
| ISSUES_FOUND | 1+ errors |
| FAILED | Invalid input (file not found, not in tests/unit/, not a test class), or a refusal from the deletion after-state check |
A fail {baseline} sets ISSUES_FOUND regardless of this table. A guard refusal sets FAILED regardless of this table and of the baseline — FAILED outranks every other status — and reason carries the tool's error text verbatim.
Track-Scoped Invocations
The team review decomposes large files into per-track reviews. Each track also receives {rules} (the pre-rendered catalog text in its prompt), so rule loading is Inline-Rules Mode selection rather than get_rules. Each track sets the inputs below:
- Method track —
test_path=…ProductServiceTest.php,methods=[testCreates, testThrows],review_unit=method. The selection predicate becomes…, scoped_review=true, review_unit=method; onlymethodrules are selected and only the named methods are judged. - Fused whole-class track —
test_path=…,review_unit=[class-structure, class-bodies], plusmethods=[…]when the review is scoped (omit for a full-class review). Reads full bodies; selects, per group, the class-structure and class-bodies rules from the inline text and unions them (one selection perreview_unitvalue). - Class-structure digest —
digest="<class shape text>", notest_pathread. Per Digest Mode: select theclass-structurerules from the inline text across groups and judge them against the digest text alone.
PHPUnit Unit Test Writing
Orchestrates the complete workflow for generating and reviewing Shopware 6 unit tests.
Core Principle
Execute immediately. Report work AFTER completion, never before.
Execution Strategy
Single File Input
Process the complete workflow (Generate → Coverage Exclusion → Review → Fix → Report) for that one file.
Multiple Files / Directory Input
Process files sequentially — one file at a time:
FOR EACH source file:
1. Generate test (wait for completion)
2. Review test (wait for completion)
3. Fix loop if needed (wait for completion)
4. Mark file complete
5. Collapse intermediate state to compact summary
THEN proceed to next file
After each file completes all phases, collapse intermediate state (generation details, review iterations, fix attempts) to a compact summary before proceeding to the next file. This prevents context growth on multi-file runs.
Autonomous Execution Rules
- No previewing — Never list tests you're about to create
- No confirmation — Never ask "should I start?" or "should I proceed?"
- Immediate action — Invoke Skill tools without hesitation
- Report after — Only explain results, not intentions. This applies to communication only — never skip workflow phases
- No phase skipping — Every phase whose entry condition is met MUST execute
File Write Restrictions
- Generation: handled by generation skill (Write tool in forked context)
- Fix loop: handled by orchestrator (Edit tool for targeted fixes)
- Coverage config: handled by orchestrator (Edit tool, Phase 2 only, user-confirmed)
Never modify:
src/**— Source codetests/integration/**— Integration tests (out of scope)- Any directory other than
tests/unit/**
Conditional modification (user confirmation required):
phpunit.xml.dist— Only adding<file>entries to<exclude>section, only during Phase 2
Workflow Phases
Phase 1: Test Generation
-
Identify the source class requiring tests
-
Invoke generation skill:
Skill(test-writing:phpunit-unit-test-generation) with source: {source_class_path} -
Parse response for:
test_path: Location of generated test filestatus: SUCCESS | PARTIAL | FAILED | SKIPPEDcategory: A | B | C | D | E (test complexity category)skip_type:coverage_excluded|no_logic(only when SKIPPED)
-
Decision:
- FAILED → Report reason to user, end workflow
- SKIPPED with
skip_type: coverage_excluded→ Report reason to user, end workflow - SKIPPED with
skip_type: no_logic→ Proceed to Phase 2 (Coverage Exclusion Offer) - SUCCESS or PARTIAL → Proceed to Phase 3
-
Update workflow state on SUCCESS/PARTIAL:
TodoWrite([ {content: "Generate unit tests", status: "completed", activeForm: "Generating unit tests"}, {content: "Review unit tests", status: "in_progress", activeForm: "Reviewing unit tests"} ])
Phase 2: Coverage Exclusion Offer
Entry condition: Generator returned SKIPPED with skip_type: no_logic.
Source files with no testable logic still appear as 0% in coverage reports unless excluded. This phase offers to add them to phpunit.xml.dist so coverage reports only show files that actually need testing.
Single-File Mode
- Read
phpunit.xml.distfrom the project root (fallback:phpunit.xml) - If not found → report SKIPPED normally, end workflow
- Locate the
<exclude>section within<coverage>/<source>(or<source>) - Verify the source file is not already excluded (guard check)
- Ask via AskUserQuestion:
Options: "Yes, exclude from coverage" / "No, skip"{source_path} was skipped — no testable logic detected ({reason}). Add it to phpunit.xml.dist coverage exclusions so it doesn't show as uncovered? - If approved:
- If
<exclude>section exists → Use Edit to add<file>{relative_path}</file>before</exclude> - If no
<exclude>section → Use Edit to insert<exclude><file>{relative_path}</file></exclude>before</source> - Record:
coverage_excluded: true
- If
- If declined → Record:
coverage_excluded: false - Report SKIPPED with coverage action taken, end workflow
Multi-File Mode
Do NOT prompt per file. Instead, collect all skip_type: no_logic files across the batch. After all files complete their workflow phases, present a single batch prompt:
X files were skipped — no testable logic detected.
Add them to phpunit.xml.dist coverage exclusions?
- src/Core/Content/Product/ProductEntity.php (Pure accessor)
- src/Core/Content/Category/CategoryCollection.php (Simple collection)
Options: "Yes, exclude all from coverage" / "No, skip"
If approved, add all <file> entries in a single Edit operation.
Phase 3: Review
MUST execute when generator returned SUCCESS or PARTIAL. Never skip.
-
Invoke reviewing skill:
Agent( agent: "test-writing:test-reviewer", prompt: "Invoke Skill(test-writing:phpunit-unit-test-reviewing) for {test_path}. Return the structured report." ) -
Parse response:
status: PASS | NEEDS_ATTENTION | ISSUES_FOUND | FAILEDerrors: Remaining must-fix rules (mandatory compliance failures)warnings: Remaining should-fix rules (optional improvements)
-
Decision:
| Status | Action |
|---|---|
| PASS | Proceed to Phase 6 (Final Report) with status COMPLIANT |
| NEEDS_ATTENTION | Proceed to Phase 4 (Fix Loop) for warnings, then Phase 5 for any unresolved |
| ISSUES_FOUND | Proceed to Phase 4 (Fix Loop) |
| FAILED | Report failure reason, end workflow |
Phase 4: Fix Loop (max 4 iterations)
Entry condition: Review returned ISSUES_FOUND (has must-fix errors).
The loop continues until ALL errors are resolved — both tool validation errors AND semantic review errors (must-fix rules from reviewing skill).
FOR iteration 1 to 4:
1. Apply ALL fixes from review report errors (Edit tool)
2. Run validation tools (code style, static analysis, tests)
3. Re-invoke reviewing skill to check for remaining issues
4. Track issue history for oscillation
5. Check exit conditions (PASS = 0 errors from review AND tools)
↓
Return final result
Step 1: Apply Fixes
For each must-fix rule with suggested fix from the review report:
- Read current file content
- Apply the reviewer's
suggestedfix using Edit tool — in full, every sub-action it specifies, not re-summarized, narrowed, or reinterpreted - Log:
{rule_id, location, attempted: true, applied: true/false, reason: null}
If a suggested fix looks wrong, do not silently substitute a partial fix — apply it as given and let the re-review and oscillation/escalation handling (Steps 3–5) catch the problem.
Priority order when fixes conflict:
- Structural errors (conditionals, class structure) — often require major changes
- Redundancy errors — may remove/merge tests
- Ordering errors — reorder test methods
- Other must-fix rules in code order
Step 2: Validate
Run code style fix, static analysis, and tests on {test_path}. Fix any errors before continuing.
Step 3: Re-invoke Reviewing Skill
Agent(
agent: "test-writing:test-reviewer",
prompt: "Invoke Skill(test-writing:phpunit-unit-test-reviewing) for {test_path}. Return the structured report."
)
Spawns test-reviewer agent → returns updated report with errors/warnings.
Step 4: Track Issue History
Maintain issue history for oscillation detection:
issue_history:
- iteration: 1
issues: ["{rule_id}:45", "{rule_id}:67"]
- iteration: 2
issues: ["{rule_id}:12"]
- iteration: 3
issues: ["{rule_id}:45"] # same rule:line returned — oscillation!
Oscillation Detection:
- Track
{rule_id}:{line_number}per iteration - If same issue appears in non-consecutive iterations → oscillation detected
- Example: {rule_id}:45 in iter 1, fixed in iter 2, returns in iter 3 = oscillation
Step 5: Exit Conditions
| Condition | Action |
|---|---|
| Review returns 0 errors AND tools pass | Exit with status: PASS |
| Oscillation detected | Handle per references/oscillation-handling.md |
| Same errors 2x consecutively | Exit as stuck loop with remaining errors |
| Iteration 4 reached with errors remaining | Exit with status: ISSUES_FOUND |
PASS Criteria (all must be met):
- Static analysis: 0 errors
- Tests: all passing
- Code style: no fixable violations
- Reviewing skill: 0 must-fix rules
ISSUES_FOUND means must-fix rules could not be resolved within 4 iterations — these are mandatory compliance failures.
Phase 5: User Decision on Warnings
If warnings remain after error correction:
- Present warnings with suggested fixes
- Ask via AskUserQuestion: "Would you like me to apply the suggested fixes for these warnings?"
- Apply fixes if user approves (Edit tool for targeted fixes, then re-run review)
Phase 6: Final Report
Provide comprehensive summary. See references/report-formats.md for templates.
Include:
- Test file path
- Final status (COMPLIANT or NON-COMPLIANT)
- Category (A-E)
- Iterations used in fix loop
- Fixes applied (list with codes)
- Remaining issues (if any)
- Warnings (if any)
Constraints
- Fix loop runs inline (max 4 iterations) with oscillation detection
- Orchestrator handles user escalation when oscillation detected
- Must-fix rules are mandatory compliance failures; should-fix rules are optional
- User input only for: Phase 2 coverage exclusion offer, Phase 5 warnings (should-fix rules), oscillation escalation
- No manual fallback — If skill invocation fails, abort workflow entirely
- Unit tests only — Do not generate or review integration tests
Error Handling
If skill invocation fails:
Workflow Aborted
Required skill `[name]` could not be invoked.
Please ensure the plugin is properly configured and try again.
Do not attempt to manually generate or review tests if skills fail.
Generation Skill Failure
If test-writing:phpunit-unit-test-generation returns FAILED:
- Report the reason to user
- Do not proceed to Phase 3
- End workflow with failure status
If SKIPPED with skip_type: coverage_excluded:
- Report the reason to user, end workflow
If SKIPPED with skip_type: no_logic:
- Proceed to Phase 2 (Coverage Exclusion Offer)
Common failure reasons:
- Source file not found
- File is interface/trait (not testable class)
- File not in
src/directory
Fix Loop Failure
If fix loop exits with ISSUES_FOUND after max iterations:
- Report remaining must-fix rules with rule IDs and locations
- Report fixes that were applied
- Report oscillation if detected
- Present current test state
Common failure reasons:
- MCP tools unavailable (PHPStan/PHPUnit/ECS)
- Test file syntax error
- Oscillation detected (handled via oscillation-handling reference)
Agents 3
Execute the task instructions provided in your spawn prompt. Do not deviate from the instructions.
Scope Constraints
- Do NOT modify any files
- Do NOT apply fixes
- Do NOT execute PHPStan/PHPUnit/ECS
- Do NOT ask questions
- Return only your result — no chatter or filler prose
Execute the task instructions provided by the invoking skill. Do not deviate from the skill's workflow.
Input Validation
Before proceeding, verify:
Input → [Single file?] → No → FAILED ("Generate for one file at a time")
↓ Yes
[Exists?] → No → FAILED
↓ Yes
[Is PHP class?] → No (interface/trait/abstract) → SKIPPED
↓ Yes
[In src/?] → No → FAILED
↓ Yes
→ Proceed with task instructions
If validation fails, return immediately with status FAILED/SKIPPED and the reason.
Scope Constraints
- Write ONLY to
tests/directory - Do NOT modify source files (
src/) - Do NOT review generated tests
- Do NOT ask questions — return structured output only
- Use ONLY MCP tools for PHP validation, NEVER Bash equivalents
Execute the task instructions provided in your spawn prompt. Do not deviate from the instructions.
Scope Constraints
- Do NOT modify any files
- Do NOT apply fixes
- Do NOT execute PHPStan/PHPUnit/ECS
- Do NOT ask questions
- Return only your result — no chatter or filler prose
MCP servers 1
Sponsors
Details
- Marketplace
- shopwareLabs/ai-coding-tools
- Source
- plugins/test-writing
- Category
- Community