| name | pc-e2e-scenario-design |
| description | Use when E2E tests must go beyond shallow happy-path checks — multi-step user journeys, stateful sessions, cross-boundary state consistency, failure-mode edges — or when the suite passes but production still breaks. Platform- and framework-agnostic (web, mobile, desktop; Playwright, XCUITest, Cypress). |
| metadata | {"phase":"05-quality","inputs":["source-code","task-list","test-strategy-doc"],"outputs":["test-suite","test-report"],"prerequisites":["pc-testing-strategy"],"quality_gate":"Scenario tests cover at least one multi-step stateful journey per critical persona; edge cases cover input boundaries, navigation failures, and dependency unavailability; no test uses fixed sleeps; assertions verify business state, not only UI visibility","roles":["qa-engineer","developer"],"methodologies":["all"],"effort":"large"} |
Deep E2E Scenario Design
Shallow tests verify that features exist. Deep tests verify that the product holds up when used.
Context
Use this skill when the existing test strategy is directionally correct, but the scenario depth is still too thin for real confidence.
See context notes.
Inputs
I/O contract notes define required inputs and authority.
Process
Step 1: Diagnose the Shallow Test Trap
Check whether the current E2E suite is mostly:
- one-screen happy-path checks
- UI visibility assertions without business-state proof
- per-feature smoke coverage with no state accumulation
- fixed-sleep timing hacks instead of deterministic waits
If that pattern dominates, treat the suite as structurally shallow before adding more cases.
Step 2: Extract Journeys from Personas
Start with real users, not the feature list. Write out what each primary persona actually does in an extended session. This is the scenario.
Step 3: Map the State Machine
For each scenario step, identify what changed and what invariants must still hold. Assert both the new state and the preserved prior state at every checkpoint.
Step 4: Identify the Re-Entry Point
Every multi-session scenario has a point where the user leaves and returns. Design one test that navigates completely away via the product's own navigation, then re-enters. This is the persistence test; a tab switch is not.
Step 5: Write Edge Cases from a Taxonomy
After the main scenario is stable, add edge cases from a deliberate taxonomy:
- input boundaries: empty, partial, max-length, invalid
- navigation boundaries: unknown route, rapid switching, deep link
- lifecycle events: interrupt/resume, process restart
- concurrency: rapid taps, optimistic-update rollback
- dependency failures: offline, timeout, partial backend availability
Suite Architecture
Organize in four layers — each with a different contract. Read references/methodology.md for the full layer definitions, implementation principles, debugging methodology, and platform-specific gotcha classes.
| Layer | Backend | Depth | Purpose |
|---|
| Fixture / stub | Controlled stub | Shallow | Routing, chrome, loading states |
| Live flow | Real backend | 2–4 steps | Per-feature smoke coverage |
| Scenario | Real backend | 8–20 steps | Multi-step session, state accumulation |
| Edge case | Real + offline | Variable | Boundaries, failure modes, lifecycle |
What to Assert
Structure and assertions are both required. Read references/assertion-patterns.md for guidance on asserting business state beyond UI visibility — including consistency across system boundaries, concurrency, and failure recovery.
Prefer assertions that prove:
- persisted business state, not just visible widgets
- cross-boundary consistency, not just local UI updates
- deterministic recovery behavior, not just eventual absence of errors
- explicit failure handling when dependencies are unavailable
Platform References
For platform-specific gotchas that cause silent failures:
Outputs
Produce only declared outputs at their documented quality boundary.
Quality Gate
Anti-Patterns
- Smoke-suite cosplay -- calling a handful of happy-path checks an E2E strategy.
- UI-only proof -- asserting that the badge or toast is visible without proving persisted or cross-boundary state.
- State reset blindness -- never leaving and re-entering the flow, so session or persistence bugs stay invisible.
- Framework cargo cult -- copying platform-specific tooling advice without tying it to the current product risk.
- Sleep-based timing -- adding fixed waits instead of deterministic state or network-based synchronization.
