# AI-Driven Happy-Path User Testing

Shared reference for `post`, `build`, and `ship`. Request-driven runtime proof for the user — not
part of the Hard QA Invariant, and never automatic. Run it only when the user explicitly asks for
a visible demo, manual/e2e user testing, happy-path proof, bug reproduction, or bug proof, or when
the build handoff explicitly requires it. For the auth-specific identity, proof-versus-setup, and
sensitive-material rules, apply `post-build-ship/references/automation-auth.md`.

## Planning (`post`)

When happy-path proof is requested, capture in the Build Handoff: target client surface
(`apps/web`, `apps/desktop`, `apps/mobile`), expected automation tool (Playwright browser /
Playwright Electron / Maestro), route or screen, auth requirements, local/test identity when relevant, demo
strategy preference, approved local/test acceleration or fallback with justification, non-printing
OTP or magic-link retrieval constraints when relevant, expected clean final visible state, expected
user-visible evidence, and any known desktop attachability or debug-port limitation. When not
requested or required, state `No AI-driven happy-path user testing requested.`

## Execution (`build`)

Run this before authoritative final QA, after the focused checks needed for a reliable proof pass.
It is a runtime proof for the user, not automatically part of the authoritative final-QA
command. Do not run visible Playwright, Playwright Electron, or Maestro user testing automatically
just because code changed. Include any screenshots, snapshots, generated files, or other proof
artifacts in the completed diff; later content changes invalidate the affected QA evidence under
`quality-assurance.md`.

1. confirm the target surface, route or screen, auth requirements, demo strategy, expected clean
   final visible state, and expected user-visible evidence from the handoff
2. start or attach to a visible session on the specified surface
3. drive the app through the requested user happy path with visible controls
4. capture the user-visible evidence named in the handoff and confirm the final state is clean,
   with no blocking overlay, permission prompt, debug menu, or keyboard
5. record the demo steps, surface, route or screen, authenticated user when relevant, strategy or
   fallback used with justification, clean final state, and observed evidence for the ship handoff

Use the visible automation tool that matches the target surface:

1. Web (`apps/web`): the Playwright browser tool in visible non-headless mode against the running app
2. Desktop/Electron (`apps/desktop`): Playwright Electron against the already-running Electron app
   through the repo-specific Playwright Electron/CDP target; select the app window or tab, not DevTools
3. Mobile (`apps/mobile` or native): Maestro against an iOS Simulator or Android emulator/device

Keep native mobile Maestro flows repository-owned. For Expo apps, place them with the app's EAS
project alongside `eas.json` so the same flow assets can run locally and through configured EAS
Workflows. Favor visible user-facing assertions plus stable accessibility identifiers or testIDs.
When the repository has no Maestro flow or command, report the absence and confirm the minimal
Maestro approach instead of improvising CLI or flow syntax or claiming proof.

For Desktop/Electron, do not confuse `DESKTOP_DEV_PORT` (the renderer dev server) with
`DESKTOP_CDP_PORT` (the Electron CDP / remote-debugging attach port used by Playwright Electron when
a repo supports stable visible dev attach). Concrete CDP port values live in the target repo's
`.env` or repo guidance, not this shared reference. Concrete origins, ports, app slugs, route names,
auth endpoint paths, headers, cookie names, storage keys, and Electron preload or storage APIs
differ per repo and live in that repo's `AGENTS.md` or docs. Read repo guidance; do not hardcode.

### Demo strategy, in preference order

1. Do not default to auth/session seeding. Prefer the real happy path through visible UI navigation
   and form submission, especially for sign-in, sign-up, profile, checkout, onboarding, or any
   auth-sensitive flow.
2. Use real UI navigation plus local/test acceleration only for external waits (email delivery,
   magic-link delivery, verification-code retrieval, seeded fixtures). Acceleration must not skip the
   UI being demonstrated unless the handoff explicitly justifies it.
3. Handle verification codes and magic links under the non-printing rules in `automation-auth.md`.
4. Use test-auth/bootstrap helpers only when auth is not the feature being demonstrated; treat them
   as setup shortcuts, not happy-path proof, and record the reason from the handoff.
5. Use direct storage, cookie, AsyncStorage, session, or IPC seeding only as a last resort, with a
   recorded reason.
6. When an e2e auth secret must be derived, derive it inside the browser or page context using
   `window.crypto.subtle`, the browser `TextEncoder`, and `btoa`.
7. Do not assume the Playwright MCP process exposes Node `fs`, `require`, `import`, `crypto`, or
   `TextEncoder`; it may not.
8. If fallback seeding is approved, seed every auth storage layer the target surface reads, using a
   non-production test identity. Web typically needs the app-origin auth cookie plus localStorage auth
   keys. Desktop/Electron typically needs the desktop-origin cookie plus both `window.localStorage`
   and Electron IPC or preload storage when available.
9. Leave the visible app on the proven screen so the user can inspect it.

If the demo cannot reproduce the expected evidence, do not stage. Treat it as a blocker, report
observed versus expected, and escalate.

## Verification (`ship`)

When happy-path testing was requested or required, `ship` refuses to commit when evidence is
absent, unclear, missing clean final-state confirmation, missing per-surface verified/skipped/
unverified status, or missing fallback justification when a fallback was used. `ship` also refuses
when the evidence includes verification codes, magic links, raw secrets, tokens, cookie values,
storage or localStorage dumps, auth headers, app key values, derived secrets, database URLs, or
auth-bypass secrets, or when it claims Desktop/Electron verification without attachment to an
app-window debug target through the repo-specific Playwright Electron/CDP target. This is the direct
enforcement gate for secret-bearing evidence and Desktop/Electron proof claims.