docs(07-01): complete playwright harness foundation plan
This commit is contained in:
Lucas Berger
@@ -0,0 +1,115 @@
|
||||
---
|
||||
phase: 07-mobile-test-harness
|
||||
plan: "01"
|
||||
subsystem: test-harness
|
||||
tags: [playwright, e2e, mobile-emulation, vitest, typecheck]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides:
|
||||
- "@playwright/test@1.60.0 devDependency in apps/pwa"
|
||||
- "playwright.config.ts with iPhone/WebKit + Pixel/Chromium matrix"
|
||||
- "test:e2e scripts in apps/pwa and root package.json"
|
||||
- "vitest glob isolation from e2e/**"
|
||||
- "tsconfig.e2e.json typecheck gate covering playwright.config.ts + e2e/"
|
||||
- "e2e/global-setup.ts stub (Plan 02 will implement)"
|
||||
affects:
|
||||
- "apps/pwa test infrastructure"
|
||||
- "Phase 07 plans 02–04 (all import from @playwright/test)"
|
||||
tech_stack:
|
||||
added:
|
||||
- "@playwright/test@1.60.0 — Playwright E2E runner with device emulation"
|
||||
- "@types/node@^22.19.19 — Node type defs for playwright.config.ts"
|
||||
- "WebKit browser engine (downloaded to ~/.cache/ms-playwright/webkit-2287)"
|
||||
- "Chromium browser engine (downloaded to ~/.cache/ms-playwright/chromium-1223)"
|
||||
patterns:
|
||||
- "tsconfig.e2e.json — separate tsconfig extending main tsconfig with node types, covers e2e/ and playwright.config.ts without contaminating src/ DOM types"
|
||||
- "vitest exclude: ['e2e/**'] — prevents Playwright *.spec.ts glob collision with jsdom runner"
|
||||
key_files:
|
||||
created:
|
||||
- apps/pwa/playwright.config.ts
|
||||
- apps/pwa/e2e/global-setup.ts
|
||||
- apps/pwa/tsconfig.e2e.json
|
||||
modified:
|
||||
- apps/pwa/package.json
|
||||
- apps/pwa/vitest.config.ts
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
decisions:
|
||||
- "D-DEV-TSCONFIG: Added tsconfig.e2e.json (separate tsconfig) rather than polluting apps/pwa/tsconfig.json with Node types — playwright.config.ts uses process.env which requires @types/node; DOM+Node type coexistence in the same tsconfig causes issues for browser-targeted src/**/*"
|
||||
- "D-DEV-GLOBALSETUP-STUB: Created e2e/global-setup.ts stub immediately because Playwright resolves globalSetup at config load time (not run time); --list and all config validation requires the file to exist"
|
||||
- "D-DEV-TYPECHECK-SCRIPT: Updated typecheck script to run both tsc passes sequentially (src + e2e) so the root pnpm -r typecheck gate covers both"
|
||||
- "D-DEV-BROWSERS-NO-DEPS: Used playwright install without --with-deps (requires sudo on this host); system deps for WebKit assumed already present; CI Dockerfile must use --with-deps"
|
||||
metrics:
|
||||
duration_seconds: 310
|
||||
completed_date: "2026-06-11"
|
||||
tasks_completed: 3
|
||||
files_changed: 7
|
||||
---
|
||||
|
||||
# Phase 07 Plan 01: Playwright Harness Foundation Summary
|
||||
|
||||
**One-liner:** Playwright test harness bootstrap — @playwright/test@1.60.0 with iPhone/WebKit + Pixel/Chromium device matrix, SW block, env-driven baseURL, and vitest/tsc isolation.
|
||||
|
||||
## What Was Built
|
||||
|
||||
The foundation for the Phase 7 mobile test harness:
|
||||
|
||||
- `@playwright/test@1.60.0` installed as a `devDependency` in `apps/pwa` (pinned, not floated)
|
||||
- WebKit (webkit-2287) and Chromium (chromium-1223) browser engines downloaded to `~/.cache/ms-playwright/`
|
||||
- `apps/pwa/playwright.config.ts` with two projects (`iphone`/WebKit, `pixel`/Chromium), `serviceWorkers: 'block'` on both, env-driven `PLAYWRIGHT_BASE_URL`, `globalSetup` ref, vite-only `webServer` with `reuseExistingServer`
|
||||
- `apps/pwa/e2e/global-setup.ts` stub (Plan 02 implements health poll + DB seed)
|
||||
- `apps/pwa/vitest.config.ts` exclude to prevent Playwright `*.spec.ts` glob collision
|
||||
- `apps/pwa/tsconfig.e2e.json` for typecheck coverage of `playwright.config.ts` + `e2e/**/*`
|
||||
- `test:e2e`, `test:e2e:ui`, `test:e2e:headed` scripts in `apps/pwa/package.json`
|
||||
- Root workspace `test:e2e` delegate script
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `pnpm --filter @familysync/pwa exec playwright --version` → `Version 1.60.0`
|
||||
- `playwright test --project=invalid` → `Available projects: "iphone", "pixel"` (exactly two)
|
||||
- `pnpm exec vitest run` → `17 passed (17), 191 passed (191)` — no e2e files attempted
|
||||
- `pnpm run typecheck` (src + e2e passes) → exits 0
|
||||
- `playwright.config.ts` grep: `serviceWorkers: 'block'` appears in both project `use` blocks; no `storageState` key; no `toHaveScreenshot`
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] globalSetup path resolves at config load time, not run time**
|
||||
- **Found during:** Task 2 verification (`playwright test --list`)
|
||||
- **Issue:** The plan stated "the reference is forward-declared and resolves at run time" but Playwright resolves `globalSetup` at config load time. `--list` failed with `Cannot find module './e2e/global-setup.ts'`.
|
||||
- **Fix:** Created `e2e/global-setup.ts` as a minimal stub exporting an empty async function. Plan 02 replaces this with the full health poll + DB seed implementation.
|
||||
- **Files modified:** `apps/pwa/e2e/global-setup.ts` (created)
|
||||
- **Commit:** 44fea2c
|
||||
|
||||
**2. [Rule 3 - Blocking] playwright.config.ts uses process.env — requires @types/node**
|
||||
- **Found during:** Task 3 `tsc --noEmit` run
|
||||
- **Issue:** `tsconfig.json` targets `lib: ["ES2023", "DOM", "DOM.Iterable"]` with no Node types. `playwright.config.ts` uses `process.env` which TS resolves from `@types/node`. Running `tsc --noEmit` with `playwright.config.ts` in scope produced 6 `Cannot find name 'process'` errors.
|
||||
- **Fix:** Created `tsconfig.e2e.json` extending the main tsconfig with `types: ["node"]` and `lib: ["ES2023"]` (no DOM), scoped to `playwright.config.ts` and `e2e/**/*`. Added `@types/node@^22.0.0` to `devDependencies`. Updated `typecheck` script to run both passes. The main `tsconfig.json` `include` stays at `["src/**/*"]` — no DOM/Node type contamination.
|
||||
- **Files modified:** `apps/pwa/tsconfig.e2e.json` (created), `apps/pwa/package.json`, `apps/pwa/vitest.config.ts`
|
||||
- **Commit:** 4536987
|
||||
|
||||
## Known Stubs
|
||||
|
||||
| Stub | File | Line | Reason |
|
||||
|------|------|------|--------|
|
||||
| Empty `globalSetup()` function | `apps/pwa/e2e/global-setup.ts` | 14 | Stub to satisfy Playwright config path resolution; Plan 02 implements health poll + DB seed (D-07/D-08) |
|
||||
|
||||
The stub does not prevent this plan's goal (harness foundation). Plan 02 is the direct dependent that resolves it.
|
||||
|
||||
## Threat Surface Scan
|
||||
|
||||
No new network endpoints, auth paths, file access patterns, or schema changes introduced. The `playwright.config.ts` and `e2e/global-setup.ts` stub are test-infrastructure files only. Threat mitigations from plan threat model:
|
||||
|
||||
- T-07-01 (DEV_AUTH_BYPASS in production): Config sets no auth-bypass itself — no new surface.
|
||||
- T-07-02 (storageState leak): `storageState` key is absent from config — designed out.
|
||||
- T-07-03 (package legitimacy): `@playwright/test@1.60.0` pinned (38.6M/wk, Microsoft); `@types/node@^22` is a Microsoft DefinitelyTyped package. No slop packages.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- `apps/pwa/playwright.config.ts` — exists
|
||||
- `apps/pwa/e2e/global-setup.ts` — exists
|
||||
- `apps/pwa/tsconfig.e2e.json` — exists
|
||||
- Task 1 commit `0c24f77` — exists
|
||||
- Task 2 commit `44fea2c` — exists
|
||||
- Task 3 commit `4536987` — exists
|
||||
Reference in New Issue
Block a user