familysync/apps/pwa/e2e

E2E Test Harness

Playwright test harness for the FamilySync PWA — mobile-emulated (iPhone 14/WebKit + Pixel 7/Chromium) and Desktop Chrome (1280×720), 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

global-setup.ts is fail-closed: it refuses to run (throws before any DB write) unless DEV_AUTH_BYPASS=true and NODE_ENV !== 'production' — the same handshake the API uses (see Security Guardrail). So DEV_AUTH_BYPASS=true must be exported in the test process environment (not only the API's). Source the DB credentials from the repo-root .env and point DB_HOST at the host-side MariaDB:

# Load DB creds, then run. DEV_AUTH_BYPASS=true is required by the global-setup guard.
set -a; source .env; set +a
export DEV_AUTH_BYPASS=true DB_HOST=127.0.0.1 DB_PORT=3306

# Full suite — iPhone (WebKit), Pixel (Chromium), Desktop Chrome profiles
pnpm --filter @familysync/pwa test:e2e

# Single profile (faster local iteration)
pnpm --filter @familysync/pwa exec playwright test --project=pixel
pnpm --filter @familysync/pwa exec playwright test --project=desktop

# 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:

0. Fail-closed guard: throws immediately if NODE_ENV === 'production' or DEV_AUTH_BYPASS !== 'true', before opening any DB connection — so the TRUNCATE/seed can never run against a production (or unconfirmed) database.
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, DB_*, and DEV_AUTH_BYPASS=true env vars in the runner environment (the global-setup guard requires DEV_AUTH_BYPASS=true in the Playwright process, not only the API's)

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