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
Choose the lifecycle boundary the product promises to survive: route change, reload, new session, or process restart. Exercise that path and identify the state source. Navigation alone can reuse client caches; a server-persistence claim needs an independent authoritative read or a fresh context that demonstrably fetches saved state.
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 | Focused | Per-feature smoke coverage |
| Scenario | Real backend | Required journey | 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:
- iOS + WKWebView (XCUITest):
references/platform/xcuitest-webview.md— document-coordinate frames, aria-modal accessibility blocking, disabled button no-ops
Outputs
Produce only declared outputs at their documented quality boundary.
Quality Gate
- At least one multi-step, stateful journey exists for each critical persona or release boundary in scope
- Edge cases cover boundaries that the upstream
test-strategy-docmarked as risky or easy to miss - Assertions verify business state or cross-boundary consistency, not just UI visibility
- No scenario relies on fixed sleeps when a deterministic wait or observable state change is available
- The resulting suite structure makes clear which cases belong to smoke, scenario, and edge-case layers
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.
Distribution
- Public install surface:
skills/.curated - Canonical authoring source:
skills/05-quality/pc-e2e-scenario-design/SKILL.md - This package is exported for
npx skills add/updatecompatibility. - Packaging stability:
beta - Capability readiness:
beta - Portability:
portable_with_caveat - Public caveat: Portable as skill guidance; full governance guarantees require the Prodcraft repository contracts and validation checks.