# E2e Testing Guide

> 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).

- Skill: `haaaiawd/e2e-testing-guide-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add haaaiawd/e2e-testing-guide-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/e2e-testing-guide-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/haaaiawd/e2e-testing-guide-2

---


# 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**.

```markdown
<!--
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>