docs(14): record planning complete + pattern map

2026-06-12 08:10:03 -04:00
parent 8742dd43a4
commit 5c3bd5c1ea
4 changed files with 261 additions and 6 deletions
@@ -0,0 +1,252 @@
+# Phase 14: Desktop E2E Coverage - Pattern Map
+
+**Mapped:** 2026-06-12
+**Files analyzed:** 5 modified files
+**Analogs found:** 5 / 5 (all files are self-analogs — modifications to existing code)
+
+---
+
+## File Classification
+
+| Modified File | Role | Data Flow | Closest Analog | Match Quality |
+|---|---|---|---|---|
+| `apps/pwa/playwright.config.ts` | config | N/A | itself (iphone/pixel project entries) | exact |
+| `apps/pwa/e2e/layout.spec.ts` | test | request-response | itself (existing describe/skip patterns) | exact |
+| `apps/pwa/e2e/calendar.spec.ts` | test | request-response | itself (test.skip at line 59 is live reference) | exact |
+| `apps/pwa/e2e/lists.spec.ts` | test | request-response | itself (all tests pass unchanged on desktop) | exact |
+| `apps/pwa/e2e/README.md` | docs | N/A | itself | exact |
+
+---
+
+## Pattern Assignments
+
+### `apps/pwa/playwright.config.ts` — add `desktop` project entry
+
+**Analog:** existing `iphone` and `pixel` project entries (lines 35–54)
+
+**Current `projects` array** (lines 35–55 — mirror this shape exactly for the third entry):
+```typescript
+projects: [
+  {
+    // iPhone 14: 390×844 viewport, WebKit engine, Mobile Safari UA, hasTouch: true
+    name: 'iphone',
+    use: {
+      ...devices['iPhone 14'],
+      serviceWorkers: 'block',
+    },
+  },
+  {
+    // Pixel 7: 412×915 viewport, Chromium engine, Chrome Android UA, hasTouch: true
+    name: 'pixel',
+    use: {
+      ...devices['Pixel 7'],
+      serviceWorkers: 'block',
+    },
+  },
+],
+```
+
+**New `desktop` entry to add** (append after the `pixel` entry, before the closing `]`):
+```typescript
+{
+  // Desktop Chrome: 1280×720 viewport, Chromium engine, no hasTouch (D-06)
+  name: 'desktop',
+  use: {
+    ...devices['Desktop Chrome'],
+    serviceWorkers: 'block',
+  },
+},
+```
+
+Key invariants to preserve (from file header comments):
+- `serviceWorkers: 'block'` — same as both mobile profiles; mandatory on every project (D-02/Pitfall 15)
+- `devices['Desktop Chrome']` — provides 1280×720, no `hasTouch`, desktop UA, Chromium engine
+- No `baseURL` override in the project entry — it is inherited from the top-level `use` block (line 29)
+- No `webServer` change — shared block at lines 57–64 applies to all projects automatically
+
+---
+
+### `apps/pwa/e2e/layout.spec.ts` — spec-compat pass (primary target)
+
+**Self-analog** — read carefully; two `test.describe` blocks need desktop skip guards, one test needs a desktop parity assertion, one test passes unchanged.
+
+#### Skip mechanism in the existing codebase
+
+The one existing `test.skip` in the suite (from `calendar.spec.ts` lines 59–62) uses the inline conditional form:
+```typescript
+test.skip(
+  !swAvailable,
+  'navigator.serviceWorker is unavailable in this context (e.g. WebKit over http://localhost) — block is unobservable here',
+);
+```
+
+This form — `test.skip(condition, reason)` called at the top of the test body — is the established pattern. Do **not** use `test.skip(testInfo.project.name === 'desktop', ...)` with a `testInfo` parameter; the simpler form without `testInfo` is consistent with what already exists.
+
+For project-name gating the correct signature requires the `testInfo` fixture:
+```typescript
+test('...', async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === 'desktop', 'reason string');
+  // ...rest of test
+});
+```
+
+Use this signature for every mobile-only test that needs a desktop skip. Keep the reason string explicit and factual (consistent with the SW-block skip's style).
+
+#### Tests in `layout.spec.ts` that need a desktop skip
+
+**Test at line 62 — "BottomTabBar is fully in-viewport (Rule 3 — safe-area-inset)":**
+```typescript
+test('BottomTabBar is fully in-viewport (Rule 3 — safe-area-inset)', async ({ page }) => {
+  // The bar uses env(safe-area-inset-bottom, 0px). In emulation there is no
+  // safe-area-inset, so the bar's bottom edge must be ≤ viewport height.
+  const nav = page.getByRole('navigation', { name: 'Main navigation' });
+  await expect(nav).toBeVisible();
+  const box = await nav.boundingBox();
+  // ...
+```
+On desktop `BottomTabBar.tsx:53-57` returns `null` at ≥768px, so this `nav` would resolve to DesktopNav sidebar and the safe-area-inset assertion is semantically wrong for a sidebar. **Skip on desktop.**
+
+**Test at line 130 — "BottomTabBar is fully in-viewport on /lists (Rule 3)"** — same reason. **Skip on desktop.**
+
+**Test at line 91 — "New Event FAB meets 56×56px touch-target minimum (Rule 1)":**
+```typescript
+test('New Event FAB meets 56×56px touch-target minimum (Rule 1)', async ({ page }) => {
+  // Phone-only FAB — aria-label="New Event", fixed 56×56px (CalendarShell.tsx)
+  const fab = page.getByRole('button', { name: 'New Event' });
+  const box = await fab.boundingBox();
+  expect(box, 'New Event FAB bounding box must not be null').not.toBeNull();
+  expect(box!.width, 'New Event FAB width ≥ 56px').toBeGreaterThanOrEqual(56);
+  expect(box!.height, 'New Event FAB height ≥ 56px').toBeGreaterThanOrEqual(56);
+});
+```
+On desktop `getByRole('button', { name: 'New Event' })` resolves to the **desktop toolbar button** (CalendarShell.tsx:436–457), not the 56×56px FAB. The toolbar button has `minHeight: 44px` but no 56px constraint. **Skip the FAB-geometry (56×56) assertion on desktop.** Per D-04, add a desktop parity block asserting ≥44px instead.
+
+Desktop parity assertion to add (new test or a conditional branch in the same test):
+```typescript
+// Desktop parity: toolbar "New Event" button meets ≥44px minimum (D-04)
+// CalendarShell.tsx:443 sets minHeight:'44px' on the desktop toolbar button.
+const toolbarBtn = page.getByRole('button', { name: 'New Event' });
+const box = await toolbarBtn.boundingBox();
+expect(box, 'New Event toolbar button bounding box must not be null').not.toBeNull();
+expect(box!.height, 'New Event toolbar button height ≥ 44px (Rule 1 desktop parity)').toBeGreaterThanOrEqual(44);
+```
+
+#### Tests that pass unchanged on desktop (no modification needed)
+
+- **"BottomTabBar navigation landmark is visible" (lines 35–41 and 108–110):** `getByRole('navigation', { name: 'Main navigation' })` resolves to DesktopNav sidebar on desktop (sole nav landmark at ≥768px). Passes as-authored.
+- **"Calendar tab meets 44×44px" / "Lists tab meets 44×44px" (lines 43–60, 112–128):** Scoped to the `Main navigation` landmark; DesktopNav sidebar links have `minHeight: 44px` (AppNav.tsx:151). Pass as-authored.
+- **"PhoneNav header is visible" (line 76):** `getByText('FamilySync', { exact: true })` matches the DesktopNav title text (AppNav.tsx:181). Passes on desktop. Verify no strict-mode collision (CONTEXT.md confirms the PhoneNav `<header>` returns null at ≥768px, leaving the DesktopNav title as the sole match).
+- **"PhoneNav settings button meets 44×44px" (line 82):** `getByRole('button', { name: /open settings/i })` is present on both PhoneNav and DesktopNav. Passes as-authored.
+- **Rule 2 overflow tests (lines 142–165):** Purely DOM measurement. Pass unchanged on desktop.
+- **Harness self-validation injected-defect proofs (lines 175–256):** Use `nav[aria-label="Main navigation"]` CSS selector and body width injection. Pass unchanged on desktop.
+
+#### `describe` block header comments to update
+
+The jsdoc block at the top of `layout.spec.ts` (lines 1–25) currently says:
+```
+ * Runs on both device profiles automatically (playwright.config.ts matrix):
+ *   iphone: iPhone 14 / WebKit / 390×844
+ *   pixel:  Pixel 7 / Chromium / 412×915
+```
+Update to list all three profiles (same update applies to all spec file headers).
+
+---
+
+### `apps/pwa/e2e/calendar.spec.ts` — no structural changes needed
+
+All tests in this file pass unchanged on desktop:
+
+- **Auth-bypass precondition (line 26):** waits for `Main navigation` landmark — resolves to DesktopNav sidebar on desktop. Passes.
+- **SW-block precondition (line 42):** already uses `test.skip(!swAvailable, ...)` — self-healing conditional. No change.
+- **Populated state tests (lines 81–111):** `.sx-react-calendar-wrapper` and `getByText('Seeded Test Event')` are not viewport-dependent. Pass unchanged.
+- **Error state tests (lines 116–178):** `page.route` + heading/button assertions are not viewport-dependent. Pass unchanged.
+
+Only the file's header comment block (lines 12–15) needs updating to list the `desktop` project.
+
+---
+
+### `apps/pwa/e2e/lists.spec.ts` — no structural changes needed
+
+All tests pass unchanged on desktop — no mobile-only assumptions anywhere in this file. Only the header comment (lines 12–15) needs updating to list the `desktop` project.
+
+---
+
+### `apps/pwa/e2e/README.md` — docs update only
+
+**Current run commands block (lines 37–47):**
+```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
+```
+
+Update the comment on the full-suite command and add a desktop-specific example:
+```bash
+# 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
+```
+
+Also update the preamble sentence (line 3) which currently says "mobile-emulated (iPhone 14/WebKit + Pixel 7/Chromium)" — add "Desktop Chrome (1280×720)".
+
+---
+
+## Shared Patterns
+
+### Project-name conditional skip
+**Source:** `apps/pwa/e2e/calendar.spec.ts` lines 59–62 (inline `test.skip` form)
+**Apply to:** every mobile-only test in `layout.spec.ts`
+
+Pattern — add as the **first statement** in the test body, before any `await`:
+```typescript
+test('test name', async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === 'desktop', 'reason: mobile-only assertion (describe which element is absent on desktop)');
+  // existing test body unchanged below
+  ...
+});
+```
+
+### Nav landmark locator (works on all three profiles)
+**Source:** `apps/pwa/e2e/layout.spec.ts` lines 45, 65; `calendar.spec.ts` lines 31, 78
+**Apply to:** any new desktop assertion that needs auth-ready confirmation
+```typescript
+const nav = page.getByRole('navigation', { name: 'Main navigation' });
+await expect(nav).toBeVisible();
+```
+On mobile: resolves to `BottomTabBar` nav. On desktop: resolves to `DesktopNav` sidebar. Same locator, different element — no conditional needed.
+
+### Desktop "New Event" button locator (CalendarShell.tsx:436–457)
+**Source:** `CalendarShell.tsx` lines 424–459
+
+The desktop toolbar button is rendered inside `{!phone && (...)}` with plain text `New Event` (no `aria-label` attribute). Playwright resolves it by accessible name from inner text:
+```typescript
+// Resolves to desktop toolbar button at ≥768px (has minHeight:44px per line 443)
+// Resolves to phone FAB at <768px (has aria-label="New Event" per line 466)
+page.getByRole('button', { name: 'New Event' })
+```
+At 1280px (`Desktop Chrome`) only the toolbar button renders; the FAB is in `{phone && (...)}` which is false. **No strict-mode collision.**
+
+---
+
+## No Analog Found
+
+None. All files being modified are established; all new code copies directly from existing patterns in the same files.
+
+---
+
+## Metadata
+
+**Analog search scope:** `apps/pwa/playwright.config.ts`, `apps/pwa/e2e/`, `apps/pwa/src/components/CalendarShell.tsx`
+**Files scanned:** 6
+**Pattern extraction date:** 2026-06-12