E2E test authoring

Purpose

Produce automation that proves user behavior and a manual scenario a tester can reproduce without prior context.

When to use

Browser E2E authoring or converting manual scenarios to automation. If a project authoring skill exists, read and follow it instead; these are fallback defaults.

Preconditions

Read the project handbook and runner config; know folder-to-project/auth/environment mapping. Verify actual routes, roles, labels and flows from current frontend source, rendered UI, or supplied HTML. Never invent selectors.

Workflow

1. Search existing specs and helpers; extend coverage without duplication. Define one outcome per case: applying and clearing a filter are separate outcomes.
2. Put the spec under its correct feature/role project. If required auth/project support is missing, report the gap rather than use the wrong session.
3. Classify data: stable fixtures for reads, uniquely identified disposable fixtures for mutations. Never edit/delete a row chosen by position. Cleanup must target only data owned by this test.
4. Use the project's ID/tag registry. For a new suite, default to TC-{PLATFORM}-{MODULE}-{NNN}, one @priority-*, and @smoke or @regression; smoke must not depend on unavailable seeded data.
5. Each functional case has a tc-doc block in the project's existing format: preconditions/role/environment, test data, exact UI actions and expected result. If no exporter/schema exists, use a simple structured comment and do not claim export support. Keep steps synchronized with the spec.
6. Prefer getByRole and getByLabel, with exact names and scoped groups where repeated labels exist. Prefer existing accessible contracts; never rename them casually. Missing accessibility is a finding; fix the product only if within authorized scope.
7. Keep specs as scenarios plus business assertions, preferably inline for single-use locators. Helpers navigate, act and synchronize; business assertions stay in specs. Mirror feature folders; separate generic utilities, shared product flows and feature helpers. Use typed Page, explicit returns and (page, options); follow existing interface naming.
8. Use observable waits and retrying assertions, not fixed sleeps. Assert real results: a filter changes the result set; a save persists after reload or an independent API read. URL or toast alone is insufficient when persistence is the objective.
9. Run the affected spec and applicable type/ID/document checks. Run a mutating scenario again to check repeatability when safe. Keep visual and accessibility snapshots in the project's separate tracks; never mix baseline updates into functional fixes.

Rules

• No conditional visibility assertions or .first() to hide ambiguity. Scope locators accurately.
• No redundant comments; intent comes from titles, manual scenario and assertions.
• Do not weaken tests for product bugs. Preserve coverage, report the bug; any skip needs an explicit reason and counts as untested.
• Do not start seeds, teardown or remote mutation runs until environment and data ownership are verified.

Common mistakes

Invented labels; wrong auth project; stable fixture mutation; helper-hidden assertions; fake smoke tags; manual steps that omit navigation; snapshot changes used as a test fix.

Validation

Confirm selectors have evidence, one outcome per test, manual/automated steps agree, fixtures are isolated and cleanup is bounded. Report actual pass/fail/skip/not-run counts and coverage gaps.