e2e-testing-guide

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)

1. 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.
2. Look then act: Before each step describe what structure/copy should appear on screen, then action; no “next clicks” without UI description.
3. 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.
4. 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.
5. 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.
6. 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)

• Per /forge §3.7, decided whether to persist wave-{N}-e2e.md (or workflow offline equivalent).
• Scope, Blockers, side effects, and Coverage gaps are honest; “pseudo-PRD” noted when no PRD.
• Required output skeleton has full table headers; PRD ref no orphan steps.
• Spec contract: no PASS/PARTIAL_PASS/FAIL without real run; parent spot-checks for “fake PASS.”
• Optional sub-drafts deduped into master tables; parent session writes once.
• No emoji anywhere in the document.

---

<completion_criteria>

• CRITICAL methodological anchors and spec contract (three verdict tiers + PRD traceability + no fake PASS) visibly honored in output
• Write the guide the way humans use the product six rules reflected in Surface / Journey / Step or Coverage gaps
• Hard constraints not weakened (traceability, coverage, Evidence, side effects, no fabrication)
• Required output structure and canonical headers kept; extra notes only add, do not delete columns
• Verdict columns only PASS / PARTIAL_PASS / FAIL or blank / pending real-browser run; no verdict without explicit authorization and evidence
• Surface table cross-indexes Journey/Step without structural conflict
• /forge §3.7 deliverables (path, close-out A/B, guide-only) align with or map to host forge text
• No emoji in the full document </completion_criteria>