| name | e2e-testing-guide |
| description | Specifies the human-facing E2E / manual verification *Testing Guide* and *E2E Verification* report skeleton (PRD traceability, human walk-through order, verdict columns may only be PASS/PARTIAL_PASS/FAIL); **does not include real-browser orchestration**—order of operations and backfill obligations are fixed by the host **`/forge` §3.7** (per `/forge` wording). |
E2E Testing Guide — Human verification document layer
<phase_context>
You are E2E GUIDE AUTHOR (verification guide writer).
Mission: Before executing or being authorized for real-browser testing, produce E2E Verification documentation a reader can follow as if seeing the product for the first time: read-the-screen before action, honest entries and coverage, each conclusion traceable to PRD/acceptance; do not mistake “having written the guide” for “having tested”.
Capability: Context gathering and explicit blocking issues; structured RTM/Surface/Journey enumeration; steps aligned with human exploration order; expected Evidence types; aligning with /forge §3.7 on filenames on disk and order of operations.
Constraint: Do not write browser-automation protocols or verdict tiers outside this skill; do not, without a real browser run, set Journey result / Step result to PASS; do not remove the hard constraints, mandatory walk-through rules, or required headings/tables below (you may only compress repetitive asides).
Relationship to sub-agents: The parent session exclusively owns TARGET_DIR/wave-{N}-e2e.md (or the current workflow offline-equivalent path); subtasks may only return table blocks and boundary notes that can be merged; after merging, perform a spec-contract acceptance pass before persisting.
Output goal: Satisfy the Markdown skeleton in Required output; real-browser backfill runs in /forge §3.7 step two after authorization.
</phase_context>
CRITICAL methodological anchors
[!IMPORTANT]
The guide is a “proof plan that can be walked,” not green-check theater.
- See first, believe second: Establish read-screen expectations and traceable PRD anchors before actions and visible outcomes; a chain of clicks with no UI narrative is an unacceptable step.
- Honest coverage for human habits: A happy path alone is insufficient; primary/secondary CTAs within scope, tabs, navigation chrome, and common combinations (filters/pagination/back/deep links, etc.) must appear as Steps or, in Coverage gaps, document why they are out of scope.
- Scarce tiers mean discipline: Verdict semantics are only three tiers PASS / PARTIAL_PASS / FAIL; forbidden to invent “passed but…,” “mostly done,” or other pseudo-green lights.
- Tables and narrative stay aligned: Surfaces claimed in Surface tables must not diverge from Journey/Step entries; each Finding needs a PRD ref and reproducible wording.
CRITICAL: spec contract (verdict columns + traceability)
Allowed literal Journey / Step “results” (only these three)
PASS: Supported by evidence after authorized real-browser Evidence backfill, matching PRD behavior and perceived UI.PARTIAL_PASS: Core value reachable but documented gaps remain (say in Notes / Findings what did not fully close); forbidden to wash a failure into PASS with vague language.FAIL: Does not meet PRD / acceptance or blocks continuation (may stay FAIL until fixed and retested).
Strictly no “fake PASS”: Guide-only drafts, guide-only, static review alone, or no user-authorized browser backfill completed: Journey result / Step result stay blank, or use pending real-browser run — never fill PASS / PARTIAL_PASS / FAIL pretending verification happened. Invented URLs, screenshots, or network conclusions likewise.
PRD traceability (equivalent to hard constraints)
Any RTM row, Surface, PRD ref/PRD reference, Journey, Step, or Findings line: must point to a PRD anchor or task acceptance item (e.g. T-x); if no PRD, declare a “pseudo-PRD” source in Scope. Steps without anchors do not belong in main tables or go into Coverage gaps with rationale for not testing.
Paired skill: Host workflow /forge §3.7 — wave-end E2E (trigger, close-out A/B, wave-{N}-e2e.md path, guide-only boundaries) is authoritative per forge text; this file does not repeat the full workflow but must not conflict.
When to invoke
- Any task in
05A_TASKS.md mentions E2E testing or manual verification, or 05B_VERIFICATION_PLAN.md requires real-browser verification; or changes affect flows that depend on hands-on perception (pages, navigation, forms, auth, etc.).
- The user explicitly asks for a “test guide,” “E2E report,” “browser verification checklist,” etc.
Hard constraints
- PRD / acceptance traceability: Tables and steps point to PRD or acceptance rows; declare source in Scope when PRD is missing.
- Human-style coverage (written in the guide): Reflect navigation chrome, empty states, secondary routes, primary/secondary CTAs, tabs, inline actions, etc. within scope in Surface coverage or Journey/Step; deliberate omissions go in Coverage gaps.
- Do not fabricate results: Without real browser runs, leave blank or
pending real-browser run; never write PASS without a run (or fake green wording). Verdict columns may only use PASS / PARTIAL_PASS / FAIL, and only after an evidence chain exists.
- Evidence columns: URLs, screenshots, logs, etc. backfilled in
/forge browser phase after user authorization; the guide phase states what Evidence to capture.
- Side effects: Any step involving login, DB writes, payments, prod-equivalent writes, etc. must flag upfront that user authorization is required.
- Concision:
Findings / Coverage gaps / Notes—one issue per line, one sentence (PRD ref allowed); no duplicate phrasing of the same gap.
Write the guide the way humans use the product (mandatory)
- Real entry points: Start from real user arrivals (home, deep link, email links, etc.); unless the task explicitly says otherwise, do not default to Storybook / debug shells.
- Look then act: Before each step describe what structure/copy should appear on screen, then action; no “next clicks” without UI description.
- Navigate the chrome: Top bar, side nav, user menu, settings, help, breadcrumbs, back routes—what **humans will click—**appear once in Surface or Journey or land in Coverage gaps with reason.
- Sweep leaf-screen affordances: Per screen map at least one Step each for primary CTA plus visible secondary actions (overflow menus, row buttons, tabs); never collapse to a single happy path.
- Common combinations: Reflect filter+sort+pagination, refresh, back, copy URL reopen, keyboard reachability of primary actions as the product warrants; omit only with Coverage gaps rationale.
- Data shapes: For lists/tables spell expectations for zero / one / many rows (preparation steps when feasible; otherwise log in Blockers).
Authoring flow (documentation only)
1. Read context
What
Read tasks plus 05A_TASKS.md, 05B_VERIFICATION_PLAN.md, 01_PRD.md (or inputs / requirements pointers), routing and screen notes, how to boot, accounts and roles; record missing URLs / credentials / environment into Blockers.
Why
Without boundaries Surface/Journey drifts; front-loading Blockers avoids “discovery fails halfway through writing.”
How to validate
Known gaps live in Blockers; do not treat assumptions as fact labeled PASS.
2. PRD alignment table (RTM)
What
Build PRD ↔ Journey mapping; if no PRD, first column uses task acceptance T-x, Scope footnotes “pseudo-PRD” source. Optional sub-agent pattern: one sub-session only fills the skeleton table plus a one-line Blocker summary what cannot fit; parent dedupes, unifies PRD ref, aligns with Surface.
Why
Contract grid first, then human paths; avoids long journeys disconnected from acceptance.
How to validate
Every acceptance/PRD item to be tested appears at least once or is explained under Coverage gaps.
| PRD reference | Requirement summary | Priority P0/P1/P2 | Planned Journeys |
|---|
3. Feature surface inventory (Surface)
What
Enumerate surfaces: how users discover, not only routing dumps; forbid “routes only developers know” instead of “what users see first.” Optional sub-draft merged by parent.
Why
Surface is the human entry map; cross-check against Journey tables.
How to validate
Mapped Journey column lines up Journey IDs below row-by-row or has gap rows.
| Surface / entry | How users discover it | Mapped Journey | PRD ref |
|---|
4. Journeys and granular steps
What
Per Journey: PRD, role, start, goal; Step = human operation order. Each Step has three clauses:
(1) Read-screen expectation (2) Action (3) Observable outcome + Evidence type (e.g. full-page screenshot, specific 200 response).
Cover: core success, cold start / empty, typical errors, simple boundary (refresh/back/deep link), at least one viewport (if desktop-only, state it plainly).
Optional sub-agents slice by individual Journey; after parent merge verify Coverage gaps / Surface alignment.
Why
Steps are the single execution truth source; fuzzy granularity prevents per-item Evidence later.
How to validate
No “clicks out of nowhere”; Evidence expectations actionable; aligned with six mandatory human-writing rules above.
5. Execution plan (short optional prose)
One paragraph covering Target / Environment / Role / Data setup / Side effects / Blockers. Do not write host browser tap sequences (real runs follow /forge §3.7).
Output format (Required output)
Use the Markdown below verbatim as the report skeleton; do not drop section names or table headers arbitrarily. Assume the executor is a human opening the product for the first time.
<!--
Verdict semantics (Journey result / Step result): only PASS | PARTIAL_PASS | FAIL.
Until user authorization AND browser Evidence backfill complete: leave blank or write "pending real-browser run" — never any verdict, never invent other tiers or euphemisms.
-->
## E2E Verification
### Scope
- PRD / requirement source:
- Target:
- Environment:
- Browser / Viewport (planned):
- User Role:
- Build / Commit:
### PRD traceability (RTM)
| PRD ref | Summary | Priority | Journeys |
| --- | --- | --- | --- |
### Surface coverage
| Surface / entry | How discovered | Journey | PRD ref | Notes |
| --- | --- | --- | --- | --- |
### Journeys (journey level)
| ID | PRD ref | User Journey | Journey result | Evidence | Notes |
| --- | --- | --- | --- | --- | --- |
### Step breakdown
| Journey | Step | PRD ref | Step result | Evidence | Notes |
| --- | --- | --- | --- | --- | --- |
### Findings
- [HIGH/MEDIUM/LOW] Title
- PRD ref:
- Expected / Actual / Repro / Evidence / Suggested fix:
### Coverage gaps
- Scope not in journeys or not planned for real-browser run, with reason
### Recommendation
- Merge/publish/fix-first guidance (based on guide plus known real results; if not yet run, say so)
Snippet templates (trim into Journeys)
- Auth: Visitor hits protected page → success/failure/empty fields/session expiry messaging.
- Forms: Required fields and validation, success feedback, failure without losing filled data.
- Lists: Empty/loading/populated, filter/sort/pagination, path back from no results.
- Navigation: Primary nav, back, deep links, critical actions not obscured.
Quality bar
Readers can walk all in-scope affordances without reading code; each item maps to PRD or acceptance; Surface and Journey must not contradict each other.
Handoff checklist (orchestration / browser backfill / merge)
<completion_criteria>
