# Playwright E2E

This directory contains both full-stack E2E tests that exercise the app through
the Vite `/api` proxy and a running local FastAPI server, and focused UI
regression tests that pin states with Playwright route fixtures. Treat a test as
DB-backed/real-API evidence only when the spec does not fulfill the endpoint
being verified and asserts the actual API response or persisted read model.

Required local services:

```sh
# apps/api
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

# apps/web, started automatically by Playwright unless already running
npm run dev -- --host 127.0.0.1 --port 5173
```

Useful overrides:

```sh
PLAYWRIGHT_PORT=5174 npm run e2e
PLAYWRIGHT_BASE_URL=http://localhost:5173 npm run e2e
VITE_API_BASE=http://127.0.0.1:8000 npm run e2e
```

Feature evidence map:

- `session-persistence.spec.ts` is the primary DB-backed evidence for session runtime flows. It covers browser `openSessionStream()` persistence, Korean PII masking through the browser stream into DB-backed detail/review payloads, crisis learner-only safety persistence without a client AI reply, AI tutor live coach history, source-pack metadata round-trip, voice metadata persistence, learner worksheet/review persistence, session-end evaluation storage, explicit teacher session/turn reevaluation, and fail-closed admin engine configuration that rejects an unreachable gateway without mutating the durable setting. The AI tutor history test must see `status=ready` and `latency_ms>0`; degraded fallback must not pass as normal engine-backed coaching.
- `kb-source-packs.spec.ts` is DB-backed source-pack sync evidence. It checks admin-only sync and source-scoped evaluator RAG lookup for the licensed source packs; evaluator retrieval 503 is a failure, not a skipped proof.
- `session-review.spec.ts` is route-fixture UI regression evidence for review states, including delayed `평가 대기` to `평가 완료` polling, `평가 실패`, `AI 평가 재시도`, and pre/post input validation states. It does not prove that the evaluator wrote a DB row unless paired with `session-persistence.spec.ts`.
- `teacher.spec.ts` mixes DB-backed teacher console paths with route-fixture queue/readability checks. Use the individual test body before citing it as persisted evidence.
- `session-mvp.spec.ts` is mostly route-fixture UI regression evidence. The AI tutor tests mock normal coaching, stale quota refresh, quota exhaustion over an old card, degraded fallback, history load failure, and runtime persistence source to prove the UI does not show replacement coaching, missing history, stale credits, or temporary storage as a silent success; the voice tests mock the browser microphone/WebSocket to prove both a final transcript followed by `turn_persistence_unavailable` and a voice `conversation_stopped` crisis reply remain visible as failure/safety states instead of successful client turns. These are not DB-backed engine success evidence.

Public Google OAuth `/turn` smoke:

```sh
# 1) Verify the public API is not accidentally serving the dev runtime.
$env:E2E_PUBLIC_AUTH="1"
npx playwright test e2e/public-auth-turn.spec.ts --project=chromium-public-auth --grep "production-safe"

# 2) Open a browser, sign in with an allowed Google account, then close codegen.
npx playwright codegen https://vignette.chanpaca.net/login --save-storage=./node_modules/.tmp/public-auth.json

# 3) Reuse that authenticated storage state for the public API turn smoke.
$env:E2E_PUBLIC_AUTH="1"
$env:E2E_PUBLIC_STORAGE_STATE="./node_modules/.tmp/public-auth.json"
npx playwright test e2e/public-auth-turn.spec.ts --project=chromium-public-auth
```

Public admin visual smoke:

```sh
# Capture storage state after signing in with an admin-entitled Google account.
npx playwright codegen https://vignette.chanpaca.net/login --save-storage=./node_modules/.tmp/public-admin-auth.json

# Verify that https://vignette.chanpaca.net/admin visibly renders the admin console.
$env:E2E_PUBLIC_AUTH="1"
$env:E2E_PUBLIC_STORAGE_STATE="./node_modules/.tmp/public-admin-auth.json"
npx playwright test e2e/public-admin-visual.spec.ts --project=chromium-public-auth
```

이 스모크에는 공식 EasyList의 과거 충돌 규칙(`.ad-root`, `.ad-section`)을 첫 paint부터
주입한 상태로 운영 홈·AI 운영·사용자·권한·티켓 5경로의 실제 가시성을 확인하는 게이트가 포함된다.
API 200, DOM 존재, selector count만으로는 통과하지 않는다.

Production lazy-chunk recovery smoke (no sign-in state required):

```powershell
$env:E2E_PREVIEW_BUILD="1"
$env:PLAYWRIGHT_SKIP_WEB_SERVER="1"
$env:PLAYWRIGHT_BASE_URL="https://vignette.chanpaca.net"
npx playwright test e2e/chunk-recovery-preview.spec.ts --project=chromium-single-run --workers=1
```

Notes:

- `E2E_PUBLIC_AUTH=1` targets the public site and does not start the local Vite web server.
- `public-auth.json` contains the HttpOnly API session cookie exported by Playwright. Treat it as sensitive and keep it under `node_modules/.tmp`.
- The API session TTL is currently 8 hours, so recapture storage state when the smoke begins returning `401`.

Install browser binaries once with:

```sh
npx playwright install chromium
```