Lucas Berger
535ba11cda
- Documents pnpm test:e2e run commands and single-profile / headed variants - Documents DEV_AUTH_BYPASS=true must be set before API starts (Pitfall 5) - States production compose MUST NOT set DEV_AUTH_BYPASS (Elevation of Privilege) - Lists PLAYWRIGHT_BASE_URL and DB_* env vars (all credentials env-only, never hardcoded) - States no storageState file is used (D-01 — no expiring session cookie) - Describes globalSetup readiness gate + seed anchors (Milk/Eggs/Seeded Test Event) - Notes Phase 8 CI scope and --with-deps WebKit requirement
105 lines
4.6 KiB
Markdown
105 lines
4.6 KiB
Markdown
# E2E Test Harness
|
|
|
|
Playwright test harness for the FamilySync PWA — mobile-emulated (iPhone 14/WebKit + Pixel 7/Chromium), authenticated via `DEV_AUTH_BYPASS`, deterministically seeded, runs headlessly in CI.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
**You bring up the dev stack first (D-09).** The harness waits for it — it does not start it.
|
|
|
|
See `docs/deployment.md` under "Running locally (host-side, no Docker)" for the canonical bring-up command.
|
|
|
|
The stack must include:
|
|
- API on `:3000` started with `DEV_AUTH_BYPASS=true` (see Security Guardrail below)
|
|
- PWA dev server on `:5173` (`pnpm --filter @familysync/pwa dev`)
|
|
- Dev MariaDB on `:3306` (exposed via `docker-compose.dev.yml`)
|
|
- Redis on `:6379`
|
|
|
|
**`DEV_AUTH_BYPASS=true` MUST be set in the API's environment BEFORE the API process starts.** The harness cannot inject it at runtime — the API reads the env var once at startup. If the API is running without it, all `/api/*` requests return an auth redirect and every spec fails.
|
|
|
|
---
|
|
|
|
## Run Commands
|
|
|
|
```bash
|
|
# Full suite — both iPhone (WebKit) and Pixel (Chromium) profiles
|
|
pnpm --filter @familysync/pwa test:e2e
|
|
|
|
# Single profile (faster local iteration)
|
|
pnpm --filter @familysync/pwa exec playwright test --project=pixel
|
|
|
|
# Headed (local debug — shows the browser)
|
|
pnpm --filter @familysync/pwa exec playwright test --headed
|
|
|
|
# UI mode (interactive test explorer)
|
|
pnpm --filter @familysync/pwa test:e2e:ui
|
|
```
|
|
|
|
---
|
|
|
|
## Env Vars
|
|
|
|
The harness reads these from the environment. DB credentials are env-only — never hardcoded in seed scripts or specs.
|
|
|
|
| Var | Default | Purpose |
|
|
|-----|---------|---------|
|
|
| `PLAYWRIGHT_BASE_URL` | `http://localhost:5173` | Base URL for all spec navigation and the /health readiness poll |
|
|
| `DB_HOST` | `127.0.0.1` | MariaDB host for the global-setup seed script |
|
|
| `DB_PORT` | `3306` | MariaDB port |
|
|
| `DB_USER` | `familysync` | MariaDB user |
|
|
| `DB_PASSWORD` | *(empty)* | MariaDB password — set in environment or `.env` |
|
|
| `DB_NAME` | `familysync` | MariaDB database name |
|
|
|
|
Set `DB_PASSWORD` (and other non-default values) via the shell or the repo root `.env` file before running. The `.env` file is gitignored — never commit credentials.
|
|
|
|
---
|
|
|
|
## Security Guardrail — DEV_AUTH_BYPASS
|
|
|
|
`DEV_AUTH_BYPASS=true` is a **development-only bypass** that resolves all API requests to Dev User id 1 without OIDC authentication.
|
|
|
|
The API enforces this via `apps/api/src/auth/devBypass.ts`:
|
|
|
|
```
|
|
if (process.env.NODE_ENV === 'production') → bypass is a no-op (always)
|
|
if (process.env.DEV_AUTH_BYPASS !== 'true') → bypass is a no-op
|
|
```
|
|
|
|
**The production Docker Compose (`docker-compose.yml`) MUST NOT set `DEV_AUTH_BYPASS`.** Setting it in production is an Elevation of Privilege vulnerability — any request would be resolved as the dev user with no authentication.
|
|
|
|
The `docker-compose.dev.yml` override sets it for local dev and CI. Review it before any production deployment to confirm `DEV_AUTH_BYPASS` is absent from the production compose file.
|
|
|
|
---
|
|
|
|
## No Session State File
|
|
|
|
This harness uses **no `storageState` file** (D-01). There is no checked-in session cookie, no expiring auth artifact, and no per-run login flow. `DEV_AUTH_BYPASS=true` makes the API respond as user 1 unconditionally — the tests run repeatably day-over-day without re-authentication. See PITFALLS.md §Pitfall 14 for why `storageState` is excluded.
|
|
|
|
---
|
|
|
|
## What globalSetup Does
|
|
|
|
Before any spec runs, `global-setup.ts`:
|
|
|
|
1. **Polls `PLAYWRIGHT_BASE_URL/health`** until 200 OK (60s timeout, then fails fast with a clear error).
|
|
2. **Truncates** `list_items`, `list_shares`, `lists`, `calendar_events` (FK checks disabled around TRUNCATE).
|
|
3. **Seeds** deterministic fixtures for Dev User 1:
|
|
- One timed calendar event (`'Seeded Test Event'`) on calendar_id=10
|
|
- One shared list (`'E2E Grocery List'`) owned by user 1, with a `list_shares` row and two items (`'Milk'`, `'Eggs'`)
|
|
|
|
This seeding is idempotent — two consecutive runs leave the same row counts, no stale rows, no duplicate-key errors.
|
|
|
|
---
|
|
|
|
## CI (Phase 8)
|
|
|
|
Phase 8 (Gitea CI) runs these specs unchanged as a PR UI-regression step. The CI workflow owns:
|
|
- Bringing up the dev stack (compose) with `DEV_AUTH_BYPASS=true`
|
|
- Waiting for the MariaDB health check before starting the API
|
|
- Setting `PLAYWRIGHT_BASE_URL` and `DB_*` env vars in the runner environment
|
|
|
|
The harness handles its own readiness gate (`/health` poll) once the runner sets things up. No changes to spec files are needed for CI — the harness is stack-agnostic via env vars.
|
|
|
|
CI Dockerfile must use `playwright install --with-deps webkit chromium` to install WebKit system deps (see RESEARCH.md §Pitfall 6).
|