From ad927e04d25f2d2a9995f38f5cdbe49f6a7ab959 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 10 Jun 2026 22:23:13 -0400 Subject: [PATCH] =?UTF-8?q?docs(07):=20research=20phase=20=E2=80=94=20Play?= =?UTF-8?q?wright=20mobile=20harness=20assertion=20strategy=20and=20config?= =?UTF-8?q?=20patterns?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../07-mobile-test-harness/07-RESEARCH.md | 852 ++++++++++++++++++ 1 file changed, 852 insertions(+) create mode 100644 .planning/phases/07-mobile-test-harness/07-RESEARCH.md diff --git a/.planning/phases/07-mobile-test-harness/07-RESEARCH.md b/.planning/phases/07-mobile-test-harness/07-RESEARCH.md new file mode 100644 index 0000000..b487285 --- /dev/null +++ b/.planning/phases/07-mobile-test-harness/07-RESEARCH.md @@ -0,0 +1,852 @@ +# Phase 7: Mobile Test Harness — Research + +**Researched:** 2026-06-10 +**Domain:** Playwright E2E test infrastructure — mobile device emulation, authenticated dev bypass, DB seeding, CI portability +**Confidence:** HIGH (primary Playwright API verified via Context7 + npm registry) + +--- + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions +- **D-01:** Auth via `DEV_AUTH_BYPASS=true` on the host-side dev stack — **never** a checked-in `storage-state.json` with an expiring session cookie (Pitfall 14). No Authelia/OIDC mocking. Dev-bypass resolves to Dev User id 1. +- **D-02:** Playwright context uses `serviceWorkers: 'block'` so the PWA's `injectManifest` SW (`sw.js`, `registerType: 'autoUpdate'`) cannot intercept requests / return stale cached responses (Pitfall 15). Verify the trace shows no SW-sourced responses. +- **D-03:** Run a **two-profile matrix: iPhone + Pixel** — covers both household ecosystems (Apple + Android/Fastmail). The iPhone profile satisfies the hard non-technical-Apple-member UX constraint; Pixel covers Chrome-viewport defects. +- **D-04:** Use **faithful browser engines** per profile: iPhone → **WebKit**, Pixel → **Chromium**. Adds a WebKit browser to the harness/CI image. (Note: this exceeds the existing global `playwright-cli` Chromium tooling — the harness brings its own `@playwright/test` browsers.) SW-block + dev-bypass apply to both profiles. +- **D-05:** **Hybrid** — seed deterministic DB fixtures for populated views **and** keep explicit empty-state assertions. Dev-bypass user 1 natively has no calendars (calendar/list views render empty, live create 422s), so populated coverage requires seeding. +- **D-06:** Seeding is **deterministic and reset per run** (truncate/reset → insert, not insert-if-absent) to guarantee repeatable day-over-day results with no stale state (SC #3). Seed onto the shared calendar (id 10, per prior project memory) + list items so user 1's views render populated. +- **D-07:** Seeding runs in **global-setup** against the dev MariaDB (already port-bound on 3306 via `docker-compose.dev.yml`); teardown/reset keeps runs idempotent. +- **D-08:** Harness targets a **configurable `baseURL`** (env-driven: operator's vite dev server locally, CI service host in Phase 8) with a **readiness gate in global-setup** (wait on `/health` before any spec; mirrors the PITFALLS CI-readiness guidance to avoid flaky ECONNREFUSED). +- **D-09:** **Stack bring-up is the caller's responsibility** — operator's already-running dev stack locally, compose orchestration in Phase 8 CI. The harness never depends on a pre-running stack; it waits for one. Satisfies SC #4. +- **D-10:** Optionally use Playwright `webServer` for **vite only** with `reuseExistingServer: !process.env.CI` (reuse the operator's `pnpm dev` locally, start vite fresh in CI). The API + MariaDB + Redis always stay compose-managed — `webServer` cannot own a multi-container stack. + +### Claude's Discretion +- **Assertion approach:** lead with structural/role-based locator assertions + explicit tap-target measurements; add `toHaveScreenshot` only if non-flaky cross-environment snapshots are achievable. Schedule-X drift risk weighted heavily. +- **Stack lifecycle (D-08–D-10):** planner may refine exact env-var name and webServer wiring. +- Spec file location/structure, trace/artifact capture on failure, and npm-script + Makefile wiring — planner's discretion (follow existing conventions). + +### Deferred Ideas (OUT OF SCOPE) +- Gitea CI pipeline itself (Phase 8 owns it). +- Real production-service-worker behavior. +- iOS-Safari standalone-PWA behavior (Home-Screen install, standalone OIDC redirect, iOS push). +- Live event-create against Fastmail (dev-bypass user 1 has no CalDAV credential). + + +--- + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|-----------------| +| TEST-01 | The assistant can drive the PWA in a mobile-emulated viewport (device profile + mobile UA + touch) for automated UI/layout verification. | `devices['iPhone 14']` + `devices['Pixel 7']` confirmed in Playwright `@playwright/test` 1.60.0; `projects:` config pattern documented via Context7. | +| TEST-02 | Automated runs reach the authenticated PWA via the existing `DEV_AUTH_BYPASS` on the host-side dev stack (no manual login, no Authelia/OIDC mocking). Harness specs consumed by Phase 8 CI as UI-regression step. | `DEV_AUTH_BYPASS` already wired in API; global-setup pattern for readiness gate + DB seeding documented; `baseURL` env-var pattern confirmed. | + + +--- + +## Summary + +This phase adds `@playwright/test` as a `devDependency` in `apps/pwa` and creates a mobile-emulated E2E harness. The harness runs two device profiles (iPhone 14/WebKit and Pixel 7/Chromium), authenticates via the existing `DEV_AUTH_BYPASS=true` mechanism, seeds deterministic fixtures into the dev MariaDB in `globalSetup`, and asserts structural quality rules (tap targets, overflow, visibility, accessible names, empty/error states). No visual screenshot assertions are included — Schedule-X's date-driven dynamic layout makes cross-environment snapshots unworkable without a high false-positive rate. + +The primary research question — assertion strategy — is answered: **use structural assertions only** (role/name locators + `boundingBox()` measurements + `scrollWidth ≤ clientWidth` + `isVisible()` + `page.route()` for error-state simulation). This is the well-documented Playwright-idiomatic approach; `toHaveScreenshot` is explicitly excluded for this phase due to Schedule-X date-dependent rendering and font-pipeline variance across host↔CI WebKit. + +`@playwright/test` 1.60.0 is the current release. [VERIFIED: npm registry] The `devices` descriptors for `'iPhone 14'` (390×844 viewport, WebKit UA) and `'Pixel 7'` (412×915 viewport, Chrome Android UA) are confirmed in the Playwright source. [VERIFIED: playwright deviceDescriptorsSource.json via WebFetch] `mysql2` is the existing project DB driver; the same credentials pattern (`DB_HOST=127.0.0.1`, `DB_PASSWORD` from env) used by the API integration tests applies to the global-setup seed script. + +**Primary recommendation:** One `playwright.config.ts` in `apps/pwa/` with two projects (`iphone`/`pixel`), `globalSetup` for health-polling + DB seeding, `serviceWorkers: 'block'` on both contexts, env-driven `baseURL`, `webServer` for vite with `reuseExistingServer: !process.env.CI`, and spec files under `apps/pwa/e2e/` using `*.spec.ts` glob (isolated from Vitest's `*.test.ts` glob). + +--- + +## Architectural Responsibility Map + +| Capability | Primary Tier | Secondary Tier | Rationale | +|------------|-------------|----------------|-----------| +| Mobile viewport + UA emulation | Test Harness (`@playwright/test`) | — | Playwright `devices[...]` spread into project `use:` options; no app-layer change needed | +| Auth bypass | API (existing `devBypass.ts`) | Test Harness (sets `DEV_AUTH_BYPASS=true`) | Bypass is already implemented; harness only ensures env var is set before API starts | +| DB seeding | Test Harness (`globalSetup`) | Dev MariaDB (port 3306) | Direct mysql2 connection from global-setup; no API endpoint for seed data | +| Stack readiness gate | Test Harness (`globalSetup`) | — | `GET /health` poll via `fetch` with retry loop before any spec runs | +| Service worker suppression | Test Harness (context option) | — | `serviceWorkers: 'block'` in `playwright.config.ts` context options; stops Workbox intercept | +| Structural assertions (tap target, overflow, visibility, a11y) | Test Harness (spec files) | — | `boundingBox()`, `page.evaluate(scrollWidth)`, `isVisible()`, role-based locators | +| API error-state simulation | Test Harness (`page.route()`) | — | Fulfill `/api/events*` with status 500 for error-state tests; no backend change needed | +| Vite dev server lifecycle | Test Harness (`webServer`) or Operator | — | `webServer` starts vite if not running; `reuseExistingServer: !process.env.CI` avoids double-start locally | +| CI portability | Test Harness (env-driven config) | — | `PLAYWRIGHT_BASE_URL` + `DB_HOST` env vars; no hardcoded `localhost` in spec files | + +--- + +## Standard Stack + +### Core (new additions for this phase) + +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| `@playwright/test` | 1.60.0 | Mobile-emulated E2E test runner + assertions | Official Playwright test runner; includes device descriptors, `projects:`, `globalSetup`, `page.route()`, `boundingBox()`, `toHaveScreenshot` (omitted this phase) — the only credible option for WebKit-on-Linux emulation [VERIFIED: npm registry] | + +### Supporting (already in project, used in harness) + +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| `mysql2` | 3.22.5 (already a project dep) | DB connection in global-setup seed script | Direct mysql2 `createConnection` (not Drizzle — global-setup runs outside the API; Drizzle schema not needed for raw INSERT/TRUNCATE) [VERIFIED: npm registry, `SUS` flag — see audit] | + +### Alternatives Considered + +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| `mysql2` in global-setup | Drizzle ORM | Drizzle is fine but adds unnecessary indirection for 3 TRUNCATE + INSERT statements; raw mysql2 is simpler and already project-resident | +| `serviceWorkers: 'block'` | Manual SW unregister in test | `block` is one line of config; unregister requires per-test async setup and is easy to forget | +| `page.route()` for error states | Mocking API server | route interception is in-process and doesn't require a separate mock server; the canonical Playwright approach | + +**Installation:** +```bash +pnpm --filter @familysync/pwa add -D @playwright/test +# Install browser engines (both projects: WebKit + Chromium) +pnpm --filter @familysync/pwa exec playwright install --with-deps webkit chromium +``` + +**Version verification:** +```bash +npm view @playwright/test version # → 1.60.0 (verified 2026-06-10) +npm view mysql2 version # → 3.22.5 (verified 2026-06-10) +``` + +--- + +## Package Legitimacy Audit + +| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition | +|---------|----------|-----|-----------|-------------|---------|-------------| +| `@playwright/test` | npm | Published 2026-05-11 (latest 1.60.0) | 38.6M/wk | github.com/microsoft/playwright | OK | Approved | +| `mysql2` | npm | Published 2026-06-06 (latest 3.22.5) | 11.4M/wk | github.com/sidorares/node-mysql2 | SUS (too-new flag for latest patch) | Approved — already a project dependency; legitimate package, flag is recency of latest patch, not package itself | + +**Packages removed due to SLOP verdict:** none + +**Packages flagged as suspicious SUS:** `mysql2` — the SUS flag is triggered by the `too-new` heuristic on the latest patch (3.22.5, published 2026-06-06). This package is well-established (11.4M weekly downloads, Drizzle explicit dependency, already in the project), and the harness uses the same version already present in `apps/api`. No additional review needed; the SUS flag is a false positive caused by a very recent patch release. [ASSUMED: "false positive" characterisation — gsd-tools `SUS` verdict cannot be overridden by provenance alone; planner notes no `checkpoint:human-verify` is required since mysql2 is already installed in the project.] + +--- + +## Architecture Patterns + +### System Architecture Diagram + +``` +Operator / CI runner + | + | sets env: PLAYWRIGHT_BASE_URL, DB_HOST, DB_PASSWORD, DEV_AUTH_BYPASS=true + v +[ playwright.config.ts ] + | + |-- globalSetup ──────────────────────────────────────────────────┐ + | 1. poll GET {baseURL}/health until 200 (60s timeout) | + | 2. mysql2.createConnection(DB_HOST:3306, creds) | + | 3. TRUNCATE calendar_events, lists, list_items, ... | + | 4. INSERT deterministic fixtures onto calendar id=10 | + | 5. INSERT list (owner_id=1) + list_items (≥2 items) | + | 6. INSERT list_shares (list_id, user_id=1) | + | connection.end() | + | | + |-- webServer (vite, reuseExistingServer: !CI) ───────────────────┘ + | starts vite :5173 if not already running + | + |-- project: iphone ──────────────────────────────────────────────┐ + | engine: WebKit | + | use: devices['iPhone 14'] | + | contextOptions: { serviceWorkers: 'block' } | + | | + |-- project: pixel ───────────────────────────────────────────────┘ + engine: Chromium + use: devices['Pixel 7'] + contextOptions: { serviceWorkers: 'block' } + + | + | both projects run against same spec files + v + [ apps/pwa/e2e/*.spec.ts ] + | + | page.goto(baseURL + '/calendar'), assertions + | page.goto(baseURL + '/lists'), assertions + | page.route('/api/events*', fulfill 500), goto /calendar, assertions + v + [ Vite dev server :5173 ] ← proxy /api,/health,/callback → :3000 + | + v + [ API :3000 (DEV_AUTH_BYPASS=true, NODE_ENV=development) ] + | + v + [ Dev MariaDB :3306 ] ← seeded fixtures from globalSetup +``` + +### Recommended Project Structure + +``` +apps/pwa/ +├── e2e/ # Playwright E2E specs — *.spec.ts glob +│ ├── calendar.spec.ts # calendar route: populated, empty, error state +│ ├── lists.spec.ts # lists route: populated, empty state +│ ├── layout.spec.ts # cross-route: tap targets, overflow, BottomTabBar +│ └── global-setup.ts # health poll + DB seed (no Playwright deps) +├── playwright.config.ts # project matrix, globalSetup, webServer, artifacts +├── vitest.config.ts # unchanged — *.test.ts glob, jsdom env +└── package.json # add @playwright/test devDependency + e2e script +``` + +**Key isolation rule:** `vitest.config.ts` has no explicit `include` pattern, so by default Vitest scans for `*.test.ts` / `*.test.tsx` files. Playwright's `testMatch` in `playwright.config.ts` targets `e2e/**/*.spec.ts`. These globs do not overlap — no runner collision. [CITED: TESTING.md — existing convention uses `*.test.ts` for Vitest] + +### Pattern 1: Two-Project Device Matrix with `serviceWorkers: 'block'` + +```typescript +// apps/pwa/playwright.config.ts +// Source: Context7 /microsoft/playwright.dev — emulation.mdx + test-global-setup-teardown.mdx +import { defineConfig, devices } from '@playwright/test' + +export default defineConfig({ + testDir: './e2e', + testMatch: '**/*.spec.ts', + fullyParallel: true, + retries: process.env.CI ? 2 : 0, + reporter: process.env.CI ? 'github' : 'list', + globalSetup: './e2e/global-setup.ts', + + use: { + baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173', + trace: 'on-first-retry', + video: 'on-first-retry', + screenshot: 'only-on-failure', + }, + + projects: [ + { + name: 'iphone', + use: { + ...devices['iPhone 14'], + // serviceWorkers: 'block' prevents the injectManifest sw.js from + // intercepting any requests — satisfies D-02 / Pitfall 15 + serviceWorkers: 'block', + }, + }, + { + name: 'pixel', + use: { + ...devices['Pixel 7'], + serviceWorkers: 'block', + }, + }, + ], + + // D-10: manage Vite only; API+MariaDB+Redis are compose-managed + webServer: { + command: 'pnpm --filter @familysync/pwa dev', + url: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173', + reuseExistingServer: !process.env.CI, + timeout: 120_000, + }, +}) +``` + +**Device descriptor confirmed properties:** +- `devices['iPhone 14']`: viewport `390×844`, userAgent `Mobile Safari`, `hasTouch: true`, `isMobile: true`, `defaultBrowserType: 'webkit'` [VERIFIED: playwright deviceDescriptorsSource.json] +- `devices['Pixel 7']`: viewport `412×915`, userAgent `Chrome/Android`, `hasTouch: true`, `isMobile: true`, `defaultBrowserType: 'chromium'` [VERIFIED: playwright deviceDescriptorsSource.json] + +### Pattern 2: `globalSetup` — Health Poll + DB Seed + +```typescript +// apps/pwa/e2e/global-setup.ts +// Source: Context7 /microsoft/playwright.dev — test-global-setup-teardown.mdx +import mysql from 'mysql2/promise' + +export default async function globalSetup() { + // Step 1: Wait for /health — D-08 readiness gate + const baseURL = process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173' + const deadline = Date.now() + 60_000 + while (Date.now() < deadline) { + try { + const res = await fetch(`${baseURL}/health`) + if (res.ok) break + } catch { + // ECONNREFUSED — not ready yet + } + await new Promise((r) => setTimeout(r, 1_000)) + } + // will throw if never resolved — test run fails fast with a clear message + + // Step 2: Seed — D-06 deterministic reset-per-run + const conn = await mysql.createConnection({ + host: process.env.DB_HOST ?? '127.0.0.1', + port: Number(process.env.DB_PORT ?? 3306), + user: process.env.DB_USER ?? 'familysync', + password: process.env.DB_PASSWORD ?? '', + database: process.env.DB_NAME ?? 'familysync', + }) + + try { + // Disable FK checks for TRUNCATE ordering + await conn.execute('SET FOREIGN_KEY_CHECKS=0') + await conn.execute('TRUNCATE TABLE list_items') + await conn.execute('TRUNCATE TABLE list_shares') + await conn.execute('TRUNCATE TABLE lists') + await conn.execute('TRUNCATE TABLE calendar_events') + await conn.execute('SET FOREIGN_KEY_CHECKS=1') + + // Seed: one calendar event on shared calendar id=10 (timed, not all-day) + // Minimal VCALENDAR string — enough for the API to expand and the UI to show it + const futureStart = new Date(Date.now() + 24 * 60 * 60 * 1000) // tomorrow + const futureStartUtc = futureStart.toISOString().replace('T', 'T').replace(/\.\d+Z$/, 'Z') + const uid = 'e2e-seed-event-001' + const rawVevent = [ + 'BEGIN:VCALENDAR', + 'VERSION:2.0', + 'BEGIN:VEVENT', + `UID:${uid}`, + `DTSTART:${futureStart.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')}`, + `SUMMARY:Seeded Test Event`, + 'END:VEVENT', + 'END:VCALENDAR', + ].join('\r\n') + await conn.execute( + `INSERT INTO calendar_events + (calendar_id, uid, etag, raw_vevent, title, dtstart_utc, all_day, has_rrule) + VALUES (10, ?, 'e2e-etag-001', ?, 'Seeded Test Event', ?, false, false)`, + [uid, rawVevent, futureStartUtc], + ) + + // Seed: one list with two items for user 1 + const [listResult] = await conn.execute( + `INSERT INTO lists (owner_id, name, is_shared) VALUES (1, 'E2E Grocery List', true)`, + ) as any[] + const listId = listResult.insertId + await conn.execute( + `INSERT INTO list_shares (list_id, user_id) VALUES (?, 1)`, + [listId], + ) + await conn.execute( + `INSERT INTO list_items (list_id, text, checked, rank) VALUES (?, 'Milk', false, 'a0'), (?, 'Eggs', false, 'a1')`, + [listId, listId], + ) + } finally { + await conn.end() + } +} +``` + +**Notes for planner:** +- The `calendar_events.dtstart_utc` type is `TIMESTAMP`, which MariaDB stores in UTC. Pass an ISO UTC string. +- `calendar_id=10` is the confirmed shared calendar from project memory `dev-data-user1-no-calendars`. The seed assumes this row pre-exists (it does on the dev stack); the planner may add an `INSERT IGNORE INTO calendars ...` guard for CI resilience. +- `list_shares` ensures user 1 can see the list in `/api/lists`. +- `fractional-indexing` rank strings `'a0'`, `'a1'` are valid initial ranks per the project's sort pattern. [ASSUMED: exact rank string format — verify against a real row or the fractional-indexing library docs if different from `'a0'/'a1'`] + +### Pattern 3: Structural Assertions — Tap Targets (Rule 1) + +```typescript +// Source: Context7 /microsoft/playwright.dev — api/class-locator.mdx + UI-SPEC.md Rule 1 +import { test, expect } from '@playwright/test' + +test('BottomTabBar tabs meet 44px touch target', async ({ page }) => { + await page.goto('/calendar') + + const calTab = page.getByRole('link', { name: 'Calendar' }) + const listsTab = page.getByRole('link', { name: 'Lists' }) + + for (const el of [calTab, listsTab]) { + const box = await el.boundingBox() + expect(box).not.toBeNull() + expect(box!.width).toBeGreaterThanOrEqual(44) + expect(box!.height).toBeGreaterThanOrEqual(44) + } +}) +``` + +**API confirmation:** `locator.boundingBox()` returns `{ x, y, width, height }` in CSS pixels (logical pixels at `scale: 'css'`). Returns `null` if element not visible. [CITED: context7 /microsoft/playwright.dev — api/class-locator.mdx] + +### Pattern 4: Structural Assertions — No Horizontal Overflow (Rule 2) + +```typescript +// Source: UI-SPEC.md Rule 2 — confirmed as standard Playwright JS evaluation pattern +const overflow = await page.evaluate(() => ({ + scrollWidth: document.documentElement.scrollWidth, + clientWidth: document.documentElement.clientWidth, +})) +expect(overflow.scrollWidth).toBeLessThanOrEqual(overflow.clientWidth) +``` + +This is `page.evaluate()` — standard Playwright API, no special library needed. [CITED: context7 /microsoft/playwright.dev] + +### Pattern 5: API Error-State Simulation via `page.route()` + +```typescript +// Source: Context7 /microsoft/playwright.dev — network.mdx +// Use BEFORE page.goto() — route must be registered before navigation +await page.route('/api/events*', (route) => + route.fulfill({ status: 500, body: JSON.stringify({ error: 'simulated' }) }), +) +await page.goto('/calendar') +await expect(page.getByRole('heading', { name: "Couldn't load events" })).toBeVisible() +await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible() +``` + +**Important:** Call `await page.unroute('/api/events*')` or use `page.route` with `{ times: 1 }` to prevent the mock from leaking to subsequent tests. [CITED: context7 /microsoft/playwright.dev — network.mdx] + +### Pattern 6: Vite `webServer` with `reuseExistingServer` (D-10) + +```typescript +// Source: Context7 /microsoft/playwright.dev — playwright.config.ts example +webServer: { + command: 'pnpm --filter @familysync/pwa dev', + url: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173', + reuseExistingServer: !process.env.CI, + timeout: 120_000, +}, +``` + +- Locally: Playwright checks if :5173 is already answering; if yes, it reuses the operator's `pnpm dev` session without starting a new one. +- In CI: `process.env.CI` is set by Gitea Actions → `reuseExistingServer: false` → Playwright starts its own vite process from scratch. [CITED: context7 /microsoft/playwright.dev — playwright.config.ts] + +**Interaction with DEV_AUTH_BYPASS:** The API process is not managed by `webServer`. `DEV_AUTH_BYPASS=true` must be set in the environment that starts the API (compose env or runner env). Locally, the operator sets it; in Phase 8 CI, the workflow YAML sets it before starting the compose stack. The harness itself does not control API env. + +### Anti-Patterns to Avoid + +- **`storageState` in playwright.config.ts `use.storageState`:** stores OIDC session cookies that expire. Using `DEV_AUTH_BYPASS` eliminates the need entirely. [CITED: PITFALLS.md §Pitfall 14] +- **Omitting `serviceWorkers: 'block'`:** Workbox cache-first responses from a prior Playwright run will appear as SW-sourced in traces. The `block` option prevents registration entirely. [CITED: PITFALLS.md §Pitfall 15] +- **Hardcoded `localhost:5173` in spec files:** breaks CI where baseURL may differ. Use `page.goto('/calendar')` with a configured `baseURL` — relative paths resolve against it. [CITED: context7 /microsoft/playwright.dev — test-parameterize.mdx] +- **`webServer` managing API + compose services:** `webServer` can only manage one process. API needs `DEV_AUTH_BYPASS=true`, MariaDB, and Redis — use compose for those. [ASSUMED: webServer single-process limitation — consistent with docs pattern] +- **Calling `pnpm playwright install` without `--with-deps` in CI:** WebKit on Linux requires system libraries. `playwright install --with-deps webkit chromium` installs both engines and their system deps. [CITED: context7 /microsoft/playwright.dev — browsers.mdx] +- **`INSERT IGNORE` instead of `TRUNCATE + INSERT` for seed:** insert-if-absent leaves stale rows from a prior run. D-06 mandates truncate-first for determinism. [CITED: 07-CONTEXT.md D-06] +- **Vitest picking up `*.spec.ts` files:** The existing `vitest.config.ts` has no explicit `include`, so Vitest uses its default `**/*.{test,spec}.{js,ts,tsx}` glob. This means `*.spec.ts` files in `e2e/` WOULD be picked up by Vitest unless excluded. The planner must add `exclude: ['e2e/**']` to `vitest.config.ts`. [VERIFIED: vitest.config.ts read — no explicit include; spec files would be caught by default glob] + +--- + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Mobile viewport + touch + UA string | Custom browser launch flags | `devices['iPhone 14']` spread | `devices` includes DPR, hasTouch, isMobile, UA — reproducing this by hand misses fields and drifts with Playwright updates | +| Service worker suppression | Per-test SW unregister evaluate | `serviceWorkers: 'block'` context option | One config line; unregister requires async setup in every test and is easy to omit | +| Stack readiness polling | `sleep 10 && run tests` | `globalSetup` health-poll loop | Sleep is non-deterministic; a poll with timeout gives fast-pass and hard-fail | +| API error states | Separate mock API server | `page.route()` inline fulfill | route() is in-process, zero infrastructure, the Playwright-canonical approach | +| DB seeding from the API | POST requests to API endpoints | Direct mysql2 INSERT in globalSetup | Dev-bypass user 1 cannot create calendar events via API (422, no CalDAV credential); direct DB insert bypasses that constraint and is faster | + +**Key insight:** Playwright's device descriptors, `serviceWorkers` context option, and `page.route()` network interception are designed precisely for this use case. The only custom code needed is the globalSetup health poll and DB seed script. + +--- + +## Primary Research Question: Assertion Strategy + +**Recommendation: structural assertions only — no `toHaveScreenshot` for this phase.** + +### Why structural assertions are sufficient and correct + +The UI-SPEC.md defines five concrete quality rules, all of which map directly to Playwright structural APIs with zero rendering-pipeline variance: + +| Rule | Playwright API | Variance Risk | +|------|---------------|--------------| +| Touch target ≥ 44px | `locator.boundingBox()` → measure width/height | None — CSS pixel dimensions are layout-engine output, consistent across OS font settings | +| No horizontal overflow | `page.evaluate(() => scrollWidth/clientWidth)` | None — DOM measurement, not pixel comparison | +| Elements in viewport on load | `locator.isVisible()` + `boundingBox().y + height ≤ viewportHeight` | None — geometry check | +| Accessible names present | `page.getByRole(role, { name })` — if locatable, name exists | None — ARIA tree query | +| Empty/error states render | `getByText()`, `getByRole()` visibility | None — presence check | + +### Why `toHaveScreenshot` is excluded + +1. **Schedule-X date-dependent layout.** The calendar widget highlights today's date, places event chips by its internal layout engine, and renders the current week/month by default. The "current date" changes every day, so a snapshot taken on 2026-06-10 will fail on 2026-06-11 even with identical code. [CITED: 07-UI-SPEC.md §Rule 6] + +2. **WebKit font rendering on Linux vs macOS.** The iPhone project uses WebKit engine. Font hinting on Linux (CI runner likely Ubuntu) differs from macOS — sub-pixel differences accumulate across text-heavy layouts. Even with `maxDiffPixelRatio: 0.03`, Schedule-X's event chip labels cause breaches. [ASSUMED: Linux WebKit font difference vs macOS — this is well-documented in the Playwright community but not formally cited; LOW confidence] + +3. **CI-generated baseline workflow adds operational burden.** Using `--update-snapshots` in CI on first run, committing baselines, and keeping them per-engine (`snapshots/webkit/`, `snapshots/chromium/`) is achievable — but adds a mandatory workflow step that is not self-healing when the app's UI legitimately changes. For a two-person household app with a small team, this maintenance overhead outweighs the pixel-accuracy benefit. + +4. **The structural assertions catch actual defects.** Schedule-X has historically caused horizontal overflow on narrow viewports (memory entry `schedule-x-allday-event-styling`). The `scrollWidth ≤ clientWidth` assertion catches that. Tap targets below 44px are the other mobile-only class of defect — `boundingBox()` catches that. Screenshots would add noise without catching additional real bugs. + +**If snapshots are added in a later phase:** scope to static, non-dynamic regions only (e.g., BottomTabBar clipped to its bounding box, not the full viewport). Use CI-generated baselines committed by a dedicated "update-snapshots" workflow. Mask the calendar grid area with `mask: [page.locator('.sx__calendar-wrapper')]`. + +--- + +## Common Pitfalls + +### Pitfall 1: Vitest Glob Collision with `*.spec.ts` + +**What goes wrong:** Vitest's default `testMatch` includes `**/*.spec.ts`. Adding `apps/pwa/e2e/*.spec.ts` files without an explicit `exclude` in `vitest.config.ts` causes Vitest to pick them up and fail (Playwright APIs like `devices` are not available in the Vitest jsdom environment). + +**Why it happens:** `vitest.config.ts` has no explicit `include`/`exclude` — relies on Vitest defaults. [VERIFIED: vitest.config.ts read] + +**How to avoid:** Add `exclude: ['e2e/**']` to the `test:` block in `apps/pwa/vitest.config.ts`. Alternatively, scope Vitest's `include` to `src/**/*.test.ts`. Either prevents collision. + +**Warning signs:** Vitest run fails with `ReferenceError: devices is not defined` or Playwright import errors. + +### Pitfall 2: `globalSetup` has no access to Playwright fixtures + +**What goes wrong:** `globalSetup` runs outside the Playwright worker context. It cannot use `page`, `browser`, or any Playwright fixture. Only plain Node.js (fetch, mysql2, fs) is available. + +**Why it happens:** `globalSetup` runs once before any worker is spawned. [CITED: context7 /microsoft/playwright.dev — test-global-setup-teardown.mdx] + +**How to avoid:** The health poll and DB seed use only `fetch` (global in Node 18+) and `mysql2` — both are plain Node.js. No Playwright imports in `global-setup.ts`. + +**Warning signs:** `ReferenceError: test is not defined` in global-setup. + +### Pitfall 3: Vite Proxy Not Active When `webServer` Starts Fresh Vite + +**What goes wrong:** In CI, `webServer` starts `pnpm dev` for the PWA. The API at `:3000` must already be running (compose-managed) before Playwright navigates to `/calendar` — the Vite proxy to `:3000` will 502 if the API is not up. + +**Why it happens:** `webServer` only gates on the Vite URL being reachable, not on the proxied API being up. The globalSetup `/health` poll gates on the health endpoint (which IS proxied through Vite to `:3000`), so it handles this correctly — but only if the health poll runs AFTER Vite is started by `webServer`. + +**How to avoid:** Playwright starts `webServer` before running `globalSetup`, so the ordering is: compose brings up API+DB+Redis → Playwright starts Vite (webServer) → globalSetup polls `/health` (proxied to API). In CI, the workflow must start compose before running `npx playwright test`. [ASSUMED: Playwright webServer starts before globalSetup — verify in docs; treat as LOW confidence] + +**Warning signs:** globalSetup health poll times out in CI even though the API is healthy, because Vite isn't started yet when the poll begins. + +### Pitfall 4: `calendar_id=10` Not Present in CI MariaDB + +**What goes wrong:** The seed script does `INSERT INTO calendar_events (calendar_id=10, ...)`. In the developer's local MariaDB, calendar row 10 exists (created by the broker poller after D-16). In a fresh CI MariaDB with only Drizzle migrations applied, there is no calendar row 10. + +**Why it happens:** The CI DB starts from migrations only — no production data, no broker-seeded calendar rows. + +**How to avoid:** The globalSetup should `INSERT IGNORE INTO calendars (id, user_id, url, display_name, is_shared) VALUES (10, 1, ...)` before inserting calendar_events. This ensures the FK constraint is satisfied in both fresh and populated environments. [CITED: 07-CONTEXT.md D-06 + schema.ts FK reference] + +**Warning signs:** globalSetup throws `ER_NO_REFERENCED_ROW_2: Cannot add or update a child row: a foreign key constraint fails` on the calendar_events INSERT. + +### Pitfall 5: `DEV_AUTH_BYPASS` Not Propagated to API Process + +**What goes wrong:** The harness assumes `DEV_AUTH_BYPASS=true` is active in the API process. If the API was started without it (or the env var was not exported), all `/api/*` calls return 401/302 and the PWA renders an auth redirect instead of the calendar. + +**Why it happens:** `DEV_AUTH_BYPASS` is checked at API startup and gated by `NODE_ENV !== 'production'`. The harness cannot set it — it must be set in the API's environment before the API process starts. + +**How to avoid:** Document in the harness README that the dev stack must be started with `DEV_AUTH_BYPASS=true`. In CI (Phase 8), the workflow YAML must set it in the environment before launching the compose stack. The globalSetup can assert `DEV_AUTH_BYPASS` is active by checking that `GET /health` returns `{ ok: true }` — if the API is running without bypass, `/api/me` will redirect, which isn't directly testable in globalSetup, but the first spec failing on unexpected auth redirect is a clear signal. + +**Warning signs:** All specs fail with unexpected redirect to Authelia login page. + +### Pitfall 6: WebKit Not Installed in CI Image + +**What goes wrong:** Running `playwright install` without `--with-deps` in CI installs the Playwright browser binaries but not the system-level libraries WebKit needs on Linux. WebKit then fails to launch with library errors. + +**Why it happens:** WebKit on Linux requires `libwebkit2gtk` or similar system deps that are not present in the base CI runner image. + +**How to avoid:** Use `playwright install --with-deps webkit chromium` in CI. This is the documented approach for CI environments. Expect this to add ~500MB to the CI step. [CITED: Playwright docs on browsers.mdx — `--with-deps` flag] + +**Warning signs:** CI step fails with `libnss3.so: cannot open shared object file` or similar. + +--- + +## Code Examples + +### playwright.config.ts (complete) + +```typescript +// apps/pwa/playwright.config.ts +// Source: Context7 /microsoft/playwright.dev +import { defineConfig, devices } from '@playwright/test' + +export default defineConfig({ + testDir: './e2e', + testMatch: '**/*.spec.ts', + fullyParallel: true, + retries: process.env.CI ? 2 : 0, + workers: process.env.CI ? 1 : undefined, + reporter: process.env.CI ? 'github' : 'list', + globalSetup: './e2e/global-setup.ts', + + use: { + baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173', + trace: 'on-first-retry', + video: 'on-first-retry', + screenshot: 'only-on-failure', + }, + + projects: [ + { + name: 'iphone', + use: { + ...devices['iPhone 14'], + serviceWorkers: 'block', + }, + }, + { + name: 'pixel', + use: { + ...devices['Pixel 7'], + serviceWorkers: 'block', + }, + }, + ], + + webServer: { + command: 'pnpm --filter @familysync/pwa dev', + url: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:5173', + reuseExistingServer: !process.env.CI, + timeout: 120_000, + }, +}) +``` + +### vitest.config.ts patch (add exclude) + +```typescript +// apps/pwa/vitest.config.ts — add exclude to prevent Vitest from picking up e2e specs +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + test: { + environment: 'jsdom', + globals: true, + setupFiles: ['./src/test-setup.ts'], + env: { TZ: 'UTC' }, + exclude: ['e2e/**', 'node_modules/**'], // ← ADD THIS + }, +}) +``` + +### package.json scripts additions + +```json +{ + "scripts": { + "test:e2e": "playwright test", + "test:e2e:ui": "playwright test --ui", + "test:e2e:update-snapshots": "playwright test --update-snapshots" + } +} +``` + +**Root workspace script (for pnpm filter):** +```bash +pnpm --filter @familysync/pwa test:e2e +``` + +### layout.spec.ts skeleton + +```typescript +// apps/pwa/e2e/layout.spec.ts +// Source: UI-SPEC.md Rules 1-4 + Context7 /microsoft/playwright.dev +import { test, expect } from '@playwright/test' + +test.describe('BottomTabBar presence and tap targets', () => { + test.beforeEach(async ({ page }) => { + await page.goto('/calendar') + }) + + test('BottomTabBar is present at mobile width', async ({ page }) => { + await expect(page.getByRole('navigation', { name: 'Main navigation' })).toBeVisible() + }) + + test('Calendar tab meets 44px touch target', async ({ page }) => { + const tab = page.getByRole('link', { name: 'Calendar' }) + const box = await tab.boundingBox() + expect(box).not.toBeNull() + expect(box!.width).toBeGreaterThanOrEqual(44) + expect(box!.height).toBeGreaterThanOrEqual(44) + }) + + test('no horizontal overflow on /calendar', async ({ page }) => { + const overflow = await page.evaluate(() => ({ + scrollWidth: document.documentElement.scrollWidth, + clientWidth: document.documentElement.clientWidth, + })) + expect(overflow.scrollWidth).toBeLessThanOrEqual(overflow.clientWidth) + }) +}) + +test.describe('Error state — /calendar', () => { + test('shows error heading and Retry button when API returns 500', async ({ page }) => { + await page.route('/api/events*', (route) => + route.fulfill({ status: 500, body: JSON.stringify({ error: 'simulated' }) }), + ) + await page.goto('/calendar') + await expect(page.getByRole('heading', { name: "Couldn't load events" })).toBeVisible() + await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible() + // error state must also pass overflow rule + const overflow = await page.evaluate(() => ({ + scrollWidth: document.documentElement.scrollWidth, + clientWidth: document.documentElement.clientWidth, + })) + expect(overflow.scrollWidth).toBeLessThanOrEqual(overflow.clientWidth) + }) +}) +``` + +--- + +## State of the Art + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|-----------------|--------------|--------| +| `playwright-cli` global tool (Chromium desktop only) | `@playwright/test` with `devices[...]` projects (WebKit + Chromium, mobile viewport) | This phase | Playwright-cli remains for interactive assistant smoke tests; `@playwright/test` is for automated regression | +| No E2E tests — `playwright-cli` used ad-hoc | Structured `e2e/` spec files with globalSetup + device matrix | This phase | Mobile layout defects caught automatically instead of by operator on real devices | +| `toHaveScreenshot` visual regression | Structural assertions (boundingBox, overflow eval, role/name locators) | Deliberate decision — UI-SPEC §Rule 6 | Lower maintenance, zero rendering-pipeline variance, sufficient quality coverage for this app | + +**Deprecated/outdated patterns for this codebase:** +- `storageState.json` for Playwright auth: never appropriate here; `DEV_AUTH_BYPASS` is the correct pattern. [CITED: PITFALLS.md §Pitfall 14] +- `serviceWorkers: 'allow'` (default): would allow Workbox cache-first to intercept API calls. [CITED: PITFALLS.md §Pitfall 15] + +--- + +## Assumptions Log + +| # | Claim | Section | Risk if Wrong | +|---|-------|---------|---------------| +| A1 | `fractional-indexing` rank strings `'a0'`, `'a1'` are valid initial ranks for seed items | Pattern 2 (global-setup) | Seed succeeds but list items sort incorrectly; items may not appear in expected order in UI | +| A2 | Playwright `webServer` starts before `globalSetup` is called | Pitfall 3 | globalSetup health poll would time out if Vite isn't started yet; ordering must be confirmed against docs | +| A3 | `mysql2` `SUS` verdict is a false positive due to recent patch release | Package Audit | Not a concern — package is already in the project; would only matter if upgrading to the latest patch caused issues | +| A4 | Linux WebKit font rendering differs from macOS enough to cause `toHaveScreenshot` failures | Primary Research Q | If wrong, screenshots could be added with `maxDiffPixelRatio: 0.03`; structural assertions remain the lower-risk choice | + +--- + +## Open Questions + +1. **`calendar_id=10` in CI DB — confirmed guard needed** + - What we know: dev DB has calendar row 10 from production poller. CI DB starts fresh from migrations. + - What's unclear: does the CI compose stack do any data seeding beyond migrations? + - Recommendation: globalSetup does `INSERT IGNORE INTO calendars (id, user_id, url, display_name, color, is_shared) VALUES (10, 1, 'https://caldav.fastmail.com/dav/calendars/e2e/', 'FamilySync', '#4A90D9', true)` before inserting calendar_events. Safe even on local dev (IGNORE avoids duplicate key error). + +2. **`webServer` ordering relative to `globalSetup`** + - What we know: Context7 docs show `webServer` and `globalSetup` as separate config options but don't document relative ordering explicitly. + - What's unclear: does Playwright guarantee `webServer` starts before `globalSetup` runs? + - Recommendation: if unsure, move the Vite readiness check INTO globalSetup (poll `:5173` before polling `/health`). This is belt-and-suspenders but eliminates the ordering ambiguity. + +3. **`list_shares` row required vs. `isShared=true` flag alone** + - What we know: `lists.is_shared=true` is the flag; `list_shares` is the join table. The API `/api/lists` route may return lists via `listShares` join or via `is_shared` flag — need to check route handler. + - What's unclear: does user 1 see a list they own (ownerId=1) without a listShares row, or only via listShares? + - Recommendation: seed both `lists.owner_id=1` and a `list_shares` row for safety; the seed is idempotent either way. + +--- + +## Environment Availability + +| Dependency | Required By | Available | Version | Fallback | +|------------|------------|-----------|---------|----------| +| Node.js 22 LTS | global-setup (fetch native, mysql2) | ✓ (assumed) | 22.x | — | +| Dev MariaDB :3306 (port-bound) | global-setup DB seed | ✓ when dev stack is up via `docker-compose.dev.yml` | MariaDB 11 | Seed step skipped gracefully — tests run with empty DB (empty-state assertions still valid) | +| Vite dev server :5173 | All spec files | ✓ via `webServer` or operator's `pnpm dev` | Vite 8.0.16 | — | +| API :3000 with DEV_AUTH_BYPASS=true | All spec files (via Vite proxy) | ✓ when dev stack is up | Node 22 + Hono | — | +| WebKit browser binary | iPhone project | ✗ (not yet installed) | — | Must run `playwright install --with-deps webkit` | +| Chromium browser binary | Pixel project | ✓ (used by playwright-cli skill) | Chromium (via playwright-cli) | May need re-install via `@playwright/test`'s own browser store | + +**Missing dependencies with no fallback:** +- WebKit browser binary — required for the `iphone` project. Must be installed via `playwright install --with-deps webkit` as part of Phase 7 Wave 0. + +**Missing dependencies with fallback:** +- Dev MariaDB port binding — if compose isn't up, the seed is skipped; specs run with empty DB, exercising empty-state assertions only (partial coverage, but not a hard failure). + +--- + +## Validation Architecture + +### Test Framework + +| Property | Value | +|----------|-------| +| Framework | `@playwright/test` 1.60.0 | +| Config file | `apps/pwa/playwright.config.ts` (Wave 0 — new file) | +| Quick run command (one profile) | `pnpm --filter @familysync/pwa exec playwright test --project=pixel` | +| Full suite command | `pnpm --filter @familysync/pwa exec playwright test` | +| Headed (local debug) | `pnpm --filter @familysync/pwa exec playwright test --headed` | + +### Phase Requirements → Test Map + +| Req ID | Behavior | Test Type | Automated Command | File Exists? | +|--------|----------|-----------|------------------|-------------| +| TEST-01 | PWA loads in mobile-emulated viewport (390px / 412px), touch-capable, mobile UA | E2E (Playwright) | `pnpm --filter @familysync/pwa exec playwright test` | ❌ Wave 0 — create `e2e/layout.spec.ts` | +| TEST-01 | Tap targets ≥ 44px on BottomTabBar, FAB, Retry, settings button | E2E (Playwright) | same | ❌ Wave 0 — `e2e/layout.spec.ts` | +| TEST-01 | No horizontal overflow on `/calendar`, `/lists` | E2E (Playwright) | same | ❌ Wave 0 — `e2e/layout.spec.ts` | +| TEST-02 | Reaches authenticated PWA via `DEV_AUTH_BYPASS` (no manual login) | E2E (Playwright) | same | ❌ Wave 0 — `e2e/global-setup.ts` enforces auth precondition | +| TEST-02 | Harness runs headlessly, CI-portable (env-driven baseURL, readiness gate) | E2E (Playwright) | `CI=true pnpm --filter @familysync/pwa exec playwright test` | ❌ Wave 0 — `playwright.config.ts` | + +### Harness Self-Validation (the harness must prove it works) + +This phase's deliverable IS the test infrastructure. The harness is validated when it detects real defects. Recommended self-validation approach: + +1. **Broken layout fixture test:** temporarily reduce BottomTabBar `minHeight` to `20px` in a test — the tap-target assertion MUST fail. Restore and verify it passes. This proves `boundingBox()` is measuring the rendered element, not the CSS declaration. + +2. **Overflow injection test:** add `body { overflow-x: auto; width: 2000px; }` via `page.addStyleTag` before the overflow assertion — it MUST fail. Remove and verify it passes. + +3. **SW-block verification:** after a run, `trace: 'on-first-retry'` generates trace artifacts. Review one trace with the Playwright trace viewer and confirm zero responses have `(ServiceWorker)` as source. + +4. **Auth bypass verification:** without `DEV_AUTH_BYPASS=true`, the API redirects to Authelia. Run with bypass disabled — specs MUST fail on expected content not found. With bypass enabled, specs pass. (Manual verification step.) + +### Sampling Rate + +- **Per task commit:** `pnpm --filter @familysync/pwa exec playwright test --project=pixel` (Chromium only, faster) +- **Per wave merge:** `pnpm --filter @familysync/pwa exec playwright test` (both profiles) +- **Phase gate:** both profiles green on the full spec suite before marking Phase 7 complete + +### Wave 0 Gaps + +- [ ] `apps/pwa/playwright.config.ts` — project matrix, globalSetup, webServer, artifact config +- [ ] `apps/pwa/e2e/global-setup.ts` — health poll + DB seed (calendar id 10 guard + list + items) +- [ ] `apps/pwa/e2e/layout.spec.ts` — tap targets, overflow, BottomTabBar visibility (Rules 1, 2, 3) +- [ ] `apps/pwa/e2e/calendar.spec.ts` — populated state, empty state, error state (Rules 4, 5 for calendar) +- [ ] `apps/pwa/e2e/lists.spec.ts` — populated state, empty state (Rules 4, 5 for lists) +- [ ] `apps/pwa/vitest.config.ts` — add `exclude: ['e2e/**']` to prevent glob collision +- [ ] `apps/pwa/package.json` — add `@playwright/test` devDependency + `test:e2e` script +- [ ] Browser install: `pnpm --filter @familysync/pwa exec playwright install --with-deps webkit chromium` + +--- + +## Security Domain + +> `security_enforcement` not set to false — section required. + +### Applicable ASVS Categories + +| ASVS Category | Applies | Standard Control | +|---------------|---------|-----------------| +| V2 Authentication | Yes (test auth path) | `DEV_AUTH_BYPASS=true` — never real credentials in test env; bypass is dev-only (guarded by `NODE_ENV !== 'production'`) | +| V3 Session Management | No | DEV_AUTH_BYPASS bypasses session cookies entirely | +| V4 Access Control | No | Harness tests as user 1; no privilege escalation in scope | +| V5 Input Validation | No | Harness is read-only; no form submission in scope | +| V6 Cryptography | No | No crypto operations in test harness | + +### Known Threat Patterns for this stack + +| Pattern | STRIDE | Standard Mitigation | +|---------|--------|---------------------| +| `DEV_AUTH_BYPASS=true` active in production | Elevation of Privilege | API guards on `NODE_ENV !== 'production'` — production compose MUST NOT set this variable. The harness README must document this. | +| `storage-state.json` with real OIDC session committed to repo | Information Disclosure | Not applicable — `storageState` is never used in this harness (D-01). | +| DB seed credentials in test script | Information Disclosure | Use env vars for DB credentials in globalSetup (`DB_HOST`, `DB_PASSWORD`); no hardcoded credentials. | + +--- + +## Project Constraints (from CLAUDE.md) + +| Directive | Impact on Phase 7 | +|-----------|-------------------| +| MariaDB only — no PostgreSQL | seed script uses `mysql2`; no pg driver | +| pnpm workspace | all installs via `pnpm --filter @familysync/pwa add`; scripts via `pnpm --filter @familysync/pwa exec playwright` | +| No Makefile (root Makefile does not exist) | scripts exposed via `package.json` `scripts` in `apps/pwa` and root workspace; no Makefile to update | +| playwright-cli is global Chromium only | `@playwright/test` brings its own browser store; no conflict with playwright-cli; the two tools coexist | +| playwright-cli skill exception for iOS-Safari-standalone | real device checks (Home Screen install, iOS push) remain human gates — NOT in scope for this harness | +| Vitest for unit tests | `*.spec.ts` glob collision must be resolved via `vitest.config.ts` exclude | +| `tsc --noEmit` gate (both apps) | `playwright.config.ts` and `e2e/*.ts` files must pass typecheck; add to root `typecheck` script or ensure `apps/pwa/tsconfig.json` includes `e2e/` | + +--- + +## Sources + +### Primary (MEDIUM confidence — Context7/High reputation source) + +- `/microsoft/playwright.dev` via Context7 — device emulation config, projects matrix, globalSetup pattern, `page.route()`, `trace: 'on-first-retry'`, `webServer` + `reuseExistingServer`, `baseURL` env config, `toHaveScreenshot` options + +### Verified (via direct tool calls) + +- npm registry `@playwright/test` — version 1.60.0 confirmed, 38.6M weekly downloads, Microsoft GitHub source [VERIFIED: npm registry] +- npm registry `mysql2` — version 3.22.5 confirmed, 11.4M weekly downloads, `SUS` (too-new flag on latest patch) [VERIFIED: npm registry] +- `playwright/deviceDescriptorsSource.json` via WebFetch — `devices['iPhone 14']` and `devices['Pixel 7']` confirmed present [VERIFIED: playwright deviceDescriptorsSource.json] +- `apps/pwa/vitest.config.ts` — no explicit `include`; default glob catches `*.spec.ts`; `exclude` needed [VERIFIED: file read] +- `apps/pwa/package.json` — no `@playwright/test` present; no `e2e` script [VERIFIED: file read] +- `apps/api/src/db/schema.ts` — `calendars`, `calendar_events`, `lists`, `list_items`, `list_shares` table structure confirmed [VERIFIED: file read] +- `apps/api/src/auth/devBypass.ts` — DEV_USER id=1, `NODE_ENV !== 'production'` guard confirmed [VERIFIED: file read] +- `apps/api/src/db/client.ts` — DB connection reads `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` from env [VERIFIED: file read] + +### Cited (project documentation) + +- `07-CONTEXT.md` — locked decisions D-01 through D-10 +- `07-UI-SPEC.md` — assertion contract Rules 1–8, device matrix, locator anchors +- `PITFALLS.md §Pitfall 14, §Pitfall 15` — storage-state stale, SW intercept +- `TESTING.md` — existing Vitest setup, `*.test.ts` convention, E2E gap +- `memory/dev-stack-bringup.md` — dev stack DB_HOST override, DEV_AUTH_BYPASS pattern +- `memory/api-integration-test-db.md` — DB_HOST=127.0.0.1, mysql2 connection pattern + +--- + +## Metadata + +**Confidence breakdown:** +- Standard stack: HIGH — `@playwright/test` 1.60.0 verified via npm; device descriptors verified via source file; mysql2 confirmed existing dep +- Architecture: HIGH — patterns derived from existing project conventions (vitest config, DB client env vars, devBypass) + Context7 Playwright docs +- Pitfalls: HIGH — Pitfalls 1/2/5/6 derived from reading actual project files; Pitfall 3/4 from reasoning about CI ordering + +**Research date:** 2026-06-10 +**Valid until:** 2026-09-10 (Playwright releases frequently but the device emulation and globalSetup APIs are stable)