Shopware ATS

Use this skill to make precise ATS changes without over-abstracting. Keep this file directive; use references/repo-map.md for detailed layout and examples.

This skill is for work inside this repository. Projects that consume the package should use the acceptance-test-suite skill from skills/ instead.

Start Here

• Open package.json, playwright.config.ts, and src/index.ts.
• Then open references/repo-map.md for merge points and edit targets.

Choose The Right Layer

Pick the narrowest owner of the behavior:

• tests/: spec flow, assertions, and coverage composition.
• src/page-objects/: selectors, URLs, and page-level affordances. See Page Object Locators below.
• src/tasks/: reusable multi-step business actions.
• src/fixtures/: context wiring, actors, lifecycle, and API/page contexts.
• src/services/TestDataService.ts: API-backed test data creation, setup, cleanup, and cleanup ordering (highPriorityEntities) for new work.
• src/services/: cross-cutting helpers and integrations.
• src/types/: shared fixture, page-object, task, and Shopware domain contracts.
• src/locales/: translation-backed assertion keys.

Treat src/data-fixtures/ as a legacy compatibility surface. Do not introduce new data-fixtures when TestDataService can own the behavior; only touch legacy fixtures to keep existing public APIs working.

If you add a reusable primitive, export it through the appropriate merge file or src/index.ts so it stays reachable from the public API.

Page Object Locators

• Initialize reusable locators as constructor-initialized readonly fields; keep methods only for parameterized locators.
• Avoid descendant CSS selector strings like .foo .bar. If CSS is unavoidable, target one stable element or scope through a named parent locator instead of encoding the hierarchy into one selector string.

When To Keep It Simple

Prefer a direct spec edit (no new abstraction) when all are true:

1. The behavior is used by one spec or one assertion path.
2. The interaction is short and readable inline.
3. Reuse is unlikely across other scenarios.

Only introduce or extend page objects, tasks, fixtures, services, or shared types when the same behavior is repeated, unstable, or clearly part of shared domain language.

Keep Surfaces Separate

Keep each browser-driven scenario on one UI surface. Do not bounce between Administration and Storefront in the same task or spec just because both fixtures are available.

In practice, that means one browser actor per scenario: ShopAdmin for Administration coverage or ShopCustomer for Storefront coverage. Neutral setup fixtures such as TestDataService, AdminApiContext, StoreApiContext, DefaultSalesChannel, or mail helpers can support either side because they do not switch the browser surface.

If a storefront scenario needs admin-side prerequisites, create them through TestDataService, AdminApiContext, or setup fixtures and then stay in Storefront. If an admin scenario needs storefront-side state, prepare it through TestDataService, StoreApiContext, or separate setup coverage instead of switching the browser surface mid-flow.

If a requested behavior truly spans both surfaces, split it into setup plus validation or into separate specs. Do not model browser flows that go Administration -> Storefront -> Administration, or the reverse.

Prefer Deterministic Setup

Follow ATS and Playwright isolation rules so tests stay parallel-safe and resilient on unknown shop states:

• Prefer TestDataService for common entity setup and cleanup.
• Extend TestDataService when the same creation logic, relation setup, or cleanup behavior would otherwise be duplicated across tests.
• Use AdminApiContext or StoreApiContext for setup and verification when the UI is not the behavior under test.
• Prefer fixture-provided contexts such as DefaultSalesChannel over mutating shared shop state.
• Create all data a scenario needs explicitly. Do not rely on existing categories, rules, flows, users, customers, or other ambient shop state.
• Do not assume default locale or currency values like en_GB or EUR; set up or fetch what the scenario needs.
• When possible, navigate directly to detail pages with entity IDs. If you must go through a listing, search with a unique name so the scenario targets one known entity.

Validate Network Responses

Check page.waitForResponse(...) responses for response.ok(), not just URL/method/payload match.

• In-predicate (... && response.ok(), see helpers/UploadMedia.ts) for search-as-you-type / debounced flows.
• Assert-after (expect(response.ok()).toBeTruthy() on the awaited response, see tasks/shop-admin/Product/BulkEditProducts.ts, SaveProduct.ts) for single-shot calls.

Cross-Repo Sync

If a change is needed in acceptance-test-suite and must be consumed immediately in a platform repository, use this workflow instead of improvising package wiring:

1. In the acceptance-test-suite project root, run npm run build.
2. Open the generated dist/ folder and copy the three index* files from that build output.
3. In the platform project root, open tests/acceptance/node_modules/@shopware-ag/acceptance-test-suite/dist/.
4. Replace the three index* files there with the files copied from acceptance-test-suite/dist/.
5. Continue with the platform-side execution or verification after those files are replaced.

Use this as the default local cross-repo sync path for ATS changes. Do not assume that installing from a sibling checkout, mixing transient npm installs, or wiring multiple Playwright runtimes together will behave the same way.

Implementation Workflow

1. Reproduce with the smallest affected spec/test block.
2. Search for existing nouns, flows, and TestDataService helpers with rg before creating new helpers.
3. Trace from spec -> actor/task -> page object -> fixture/service/type and fix the owning layer.
4. Keep established patterns (mergeTests, test.extend, locale-aware assertions, and the actor model where it improves readability). The actor pattern is optional; plain Playwright is still valid when it is clearer. For Storefront flows, prefer ShopCustomer.fillsIn() and ShopCustomer.presses() where existing tasks already use that keyboard-first pattern; do not generalize that rule to Administration flows.
5. Keep version or SaaS branching explicit when tied to InstanceMeta.
6. Re-export new reusable surfaces via the right merge file or src/index.ts.
7. Keep page objects structural: constructor-initialize fixed readonly locators, use methods only for parameterized locators, and move multi-step behavior into tasks, services, or helper classes. When the behavior is a reusable browser-driven business action, prefer a task over a local spec helper function. For locators, prefer semantic single-target queries over chained CSS descendants; do not introduce selectors like .parent .child when a direct accessible locator or a scoped named parent locator would be clearer and less brittle.
8. Keep ShopAdmin.expects(...) or ShopCustomer.expects(...) in the spec or the owning task, but keep the verification intent obvious from the spec. A reader should be able to tell what behavior the scenario proves without digging through helper layers.
9. When a fix must be verified in a consuming repo, sync the built ATS dist/index* files into the consumer's tests/acceptance/node_modules/@shopware-ag/acceptance-test-suite/dist/ folder before retrying the spec.

Keep Specs High-Signal

When writing or refactoring ATS specs:

• Assert only what materially proves the behavior. Avoid duplicate visibility/count/text checks that restate the same fact with more noise.
• Favor a few high-signal assertions over exhaustive UI restatement. The goal is confidence in behavior, not a transcript of the page.
• Keep the verified outcome legible at spec level. Even when an owning task contains ShopAdmin.expects(...) or ShopCustomer.expects(...), the spec should still make the proven behavior obvious from its setup, action, and named verification step.

Don't

• Do not hide most expect(...) calls inside helpers, tasks, or page objects. Those layers should usually return locators, values, or perform actions; only extract an expect... helper when the assertion is a shared domain primitive.
• Do not wrap ShopAdmin.expects(...) or ShopCustomer.expects(...) inside generic helper methods. Keep actor-scoped expectations in the spec or the owning task, and make the verification intent clear from the spec so the reader can see what is being proven.
• Do not introduce ad hoc local helper functions for repeated browser-driven flows when the same interaction belongs in a reusable task. If the behavior is a shared business action, model it as a task instead of a spec-local helper.
• Do not repeat explicit timeouts when Playwright's configured defaults already express the intended wait. Add a custom timeout only when one wait is genuinely exceptional and the reason is clear from the scenario.
• Do not split tiny actions or single assertions into separate test.step(...) blocks.
• Do not combine ShopAdmin and ShopCustomer UI actions in one browser-driven task or spec. If both surfaces are involved, use API or fixture setup for prerequisites and keep the UI flow on one side.
• Do not assume a list, table, or API helper returns only one item. Use unique names or IDs so the scenario identifies the exact entity it created.
• Do not request unused fixtures. If the spec does not read from a fixture, remove it or refactor the setup.
• Do not depend on implicit configuration or pre-existing shop data.
• Do not change global settings unless the scenario explicitly owns that scope; prefer sales-channel-specific setup and isolated test data.
• Do not stack duplicate visibility, count, and text assertions that restate the same fact with more noise.
• Do not turn a spec into a transcript of the page. Keep assertions focused on the few signals that materially prove the behavior.

Validate

Run the narrowest useful checks first:

• npx playwright test tests/<spec>.spec.ts --project=chromium
• npm run lint
• npm run typecheck
• npm run build

For environment defaults and boot behavior, rely on playwright.config.ts and the reference file instead of hardcoding assumptions.

Grow This Skill From Review Feedback

When a review — human or agent — traces a mistake back to a gap in this skill rather than a one-off code error, propose a concrete addition:

• Only if the pattern already recurs across multiple files here and would not have surfaced from a minute of rg before writing the code — otherwise it is a one-off, not a skill gap.
• Rule plus real precedent file(s) only (see Validate Network Responses above for the format), no narrative justification.
• Mark an expiry condition when the rule is tied to a transitional state (an in-progress migration, a pattern being phased out), the same way //TODO: After 6.8.0.0 release... comments already mark code for cleanup.
• If rules like this start crowding the file, consolidate into a references/ file and leave a pointer here instead (see how Start Here delegates to references/repo-map.md).
• Get the user's or reviewer's sign-off on wording and placement before committing it here.