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