---
phase: 7
slug: mobile-test-harness
status: draft
shadcn_initialized: false
preset: none
created: 2026-06-11
framing: quality-bar-contract
---

# Phase 7 — Mobile UI Quality-Bar Contract

> This phase builds **no new UI**. The harness asserts against the existing
> FamilySync PWA. This document is a **quality-bar contract**, not a design
> system spec. Its job is to pin every measurable threshold the harness must
> enforce so the planner can turn each rule into a concrete Playwright
> assertion. Template sections that have no assertable content for a test
> harness are marked N/A with a one-line reason.

---

## Design System

N/A — test harness, no new UI. The existing design system is declared in
`apps/pwa/src/styles/tokens.css` and consumed by the assertions below.

| Property | Value |
|----------|-------|
| Tool | none (no shadcn; inline CSS custom properties) |
| Preset | not applicable |
| Component library | none (lucide-react icons; Schedule-X calendar widget) |
| Icon library | lucide-react (via npm dep, no CDN) |
| Font | `system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` |

---

## Spacing Scale

N/A — test harness, no new UI. Spacing tokens are declared in `tokens.css`
and are not re-specified here. Assertions reference computed pixel values
derived from those tokens where needed (e.g. BottomTabBar height = 56px +
safe-area-inset).

---

## Typography

N/A — test harness, no new UI. Typography tokens exist in `tokens.css`; the
harness does not assert on font metrics unless a visible-text / accessible-name
check requires it (captured in Assertion Contract below).

---

## Color

N/A — test harness, no new UI. The 60/30/10 color split is declared in
`tokens.css`. The harness does not assert computed colors — color drift is
out of scope and prone to rendering-pipeline variance.

---

## Copywriting Contract

Copywriting that the harness **must** be able to locate by text in assertions.
These are the exact strings emitted by the existing components; the harness
uses them as stable locator anchors.

| Element | Exact String | Source Component |
|---------|-------------|------------------|
| Calendar empty-state heading | `Nothing here` | `EmptyState.tsx` |
| Calendar empty-state body | `No events in this period. Try a different date or switch views.` | `EmptyState.tsx` |
| Lists empty-state heading | `No lists yet` | `ListsEmptyState.tsx` |
| Lists empty-state body | `Tap + to create your first shared list` (contains) | `ListsEmptyState.tsx` |
| Calendar error heading | `Couldn't load events` | `CalendarShell.tsx` |
| Calendar error CTA | `Retry` (button text) | `CalendarShell.tsx` |
| New Event FAB | `aria-label="New Event"` | `CalendarShell.tsx` |
| Bottom nav — Calendar tab | `aria-label="Calendar"` | `BottomTabBar.tsx` |
| Bottom nav — Lists tab | `aria-label="Lists"` | `BottomTabBar.tsx` |
| Top nav (phone) | `FamilySync` (visible text) | `AppNav.tsx` — `PhoneNav` |
| Settings button | `aria-label` contains `open settings` | `AppNav.tsx` — `PhoneNav` |

> Stable copywriting anchor rule: **always locate interactive elements by
> `aria-label` or `role` + accessible name first.** Text-content locators
> (`getByText`) are second resort — acceptable for static headings/bodies
> that have no ARIA role.

---

## Registry Safety

N/A — test harness, no new UI components. `@playwright/test` is a new dev
dependency in `apps/pwa`; it is the official Playwright package from the
Playwright team and requires no safety vetting under this gate.

---

## Assertion Contract

This section is the primary deliverable for Phase 7. It replaces the
design-system sections of the standard template with the measurable
quality-bar rules that the harness enforces.

### Device / Viewport Matrix

| Profile ID | Playwright Descriptor | Engine | Viewport | UA Type |
|---|---|---|---|---|
| `iphone` | `'iPhone 14'` | WebKit | 390×844 logical px | Mobile Safari |
| `pixel` | `'Pixel 7'` | Chromium | 412×915 logical px | Chrome Android |

**Source:** D-03 (iPhone + Pixel matrix), D-04 (WebKit for iPhone, Chromium
for Pixel). These are the exact Playwright device descriptor strings to pass
to `devices['iPhone 14']` and `devices['Pixel 7']` in `playwright.config.ts`.

Both profiles run with `serviceWorkers: 'block'` (D-02 / Pitfall 15) and
`DEV_AUTH_BYPASS=true` (D-01 / Pitfall 14). No `storageState` file.

**CI note:** Both engines must be installed in the Phase 8 CI image. The
harness adds WebKit beyond the existing global `playwright-cli` (Chromium
only). Accept the larger CI image cost — this was a deliberate call (D-04,
07-CONTEXT.md §Specifics).

---

### Rule 1 — Touch-Target Minimum

**Threshold:** Every interactive element (button, link, `role="button"`) must
have a computed bounding box of **≥ 44 × 44 logical pixels**.

**Basis:**
- Apple Human Interface Guidelines: minimum touch target 44×44 pt.
- WCAG 2.5.5 (Level AAA): minimum 44×44 CSS px.
- The existing codebase declares this as a hard constraint: `BottomTabBar`
  uses `minHeight: '44px'`; `AppNav` `PhoneNav` settings button uses
  `minWidth: '44px', minHeight: '44px'`; calendar FAB is `56×56px`; Retry
  button uses `minHeight: '44px'`; nav links use `minHeight: '44px'`.

**Measurement approach:**
```typescript
// Use boundingBox() on the element handle, not CSS-declared values.
const box = await element.boundingBox()
expect(box!.width).toBeGreaterThanOrEqual(44)
expect(box!.height).toBeGreaterThanOrEqual(44)
```

**What counts as an interactive target:**
- `<button>` elements (including FAB, Retry, settings avatar button)
- `<a>` and `NavLink` elements (BottomTabBar tabs, sidebar nav links)
- Any element with `role="button"`, `role="link"`, or `tabindex="0"` that
  has a click/tap handler

**Explicit elements to assert on both profiles:**

| Element | Expected min size | Locator strategy |
|---|---|---|
| BottomTabBar Calendar tab | 44×44 | `getByRole('link', { name: 'Calendar' })` |
| BottomTabBar Lists tab | 44×44 | `getByRole('link', { name: 'Lists' })` |
| PhoneNav settings button | 44×44 | `getByRole('button', { name: /open settings/i })` |
| New Event FAB | 56×56 | `getByRole('button', { name: 'New Event' })` |
| Retry button (error state) | 44×44 | `getByRole('button', { name: 'Retry' })` |

**BottomTabBar phone-only gate:** `BottomTabBar` renders `null` on desktop
(`matchMedia('(max-width: 767px)')`). Assert it is present on both mobile
profiles (390px and 412px width) and absent on desktop (1280px). Both test
profiles qualify as phone-width so the bar must be visible.

---

### Rule 2 — No Horizontal Overflow

**Threshold:** On every tested route, `document.documentElement.scrollWidth`
must equal `document.documentElement.clientWidth`. No horizontal scrollbar;
no content overflow.

**Measurement approach:**
```typescript
const overflow = await page.evaluate(() => ({
  scrollWidth: document.documentElement.scrollWidth,
  clientWidth: document.documentElement.clientWidth,
}))
expect(overflow.scrollWidth).toBeLessThanOrEqual(overflow.clientWidth)
```

**Routes to assert on both profiles:**

| Route | State to assert |
|---|---|
| `/calendar` | populated (seeded events) |
| `/calendar` | error state (simulated — mock API to 500) |
| `/lists` | populated (seeded list + items) |
| `/lists` | empty state (no lists — dev-bypass user 1 native state) |

**Allowed exceptions:** none. The Schedule-X calendar widget historically
caused overflow on narrow viewports (see memory entry `schedule-x-allday-event-styling`).
If a Schedule-X internal element overflows, the assertion must still fail —
this is the defect the harness exists to catch.

---

### Rule 3 — Critical Elements Visible and In-Viewport

Assertion: each element below must be visible (`isVisible() === true`) **and**
within the viewport (`boundingBox().y >= 0`, `boundingBox().y + height <=
viewport.height`) on initial load, before any scroll.

| Element | Route | Profile |
|---|---|---|
| BottomTabBar | `/calendar`, `/lists` | iPhone + Pixel |
| PhoneNav header | `/calendar`, `/lists` | iPhone + Pixel |
| Schedule-X calendar grid | `/calendar` (populated) | iPhone + Pixel |
| New Event FAB | `/calendar` | iPhone + Pixel |
| Lists index cards (≥1 card) | `/lists` (seeded) | iPhone + Pixel |

**BottomTabBar position assertion (safe-area-inset):** the bar uses
`env(safe-area-inset-bottom, 0px)`. In the emulated context there is no
safe-area-inset, so the bar's bottom edge must be ≤ the viewport height.
Assert `boundingBox().y + boundingBox().height <= page.viewportSize().height`.

---

### Rule 4 — Accessible Names on All Interactive Elements

Assertion: every interactive element exposed to the assertions above must
have a non-empty accessible name, locatable via Playwright's ARIA role
queries without needing a CSS selector fallback.

**Required accessible names (exact or pattern):**

| Element | Role | Expected accessible name |
|---|---|---|
| BottomTabBar Calendar tab | `link` | `"Calendar"` |
| BottomTabBar Lists tab | `link` | `"Lists"` |
| PhoneNav settings button | `button` | matches `/open settings/i` |
| New Event FAB | `button` | `"New Event"` |
| Retry button | `button` | `"Retry"` |
| Main navigation landmark | `navigation` | `"Main navigation"` |

Locator pattern:
```typescript
page.getByRole('link', { name: 'Calendar' })
page.getByRole('button', { name: /open settings/i })
```

If an element cannot be found by role + name, the test fails. This doubles as
a regression gate for accessible-name regressions (e.g. a button losing its
`aria-label`).

---

### Rule 5 — Empty States Render Correctly

**Context (D-05):** DEV_AUTH_BYPASS user 1 natively has no CalDAV credentials
or calendars. Without seeding, calendar views render empty and list views
render empty. This is the "native empty" state.

**Seeded populated state:** D-06 seeds deterministic fixtures before each run
(global-setup truncate/insert). Seeding targets shared calendar id 10 (from
project memory `dev-data-user1-no-calendars`) and creates ≥1 list with ≥2
items for user 1 (via direct MariaDB insert, not the API, since live
event-create 422s for user 1).

**Assertions:**

| State | Route | Assert |
|---|---|---|
| Populated calendar | `/calendar` (after seeding) | Schedule-X grid is visible; `<EmptyState>` is NOT in DOM |
| Populated lists | `/lists` (after seeding) | ≥1 list card is visible; `ListsEmptyState` is NOT in DOM |
| Empty lists (pre-seed teardown or clean run) | `/lists` | `getByText('No lists yet')` is visible; `getByText(/Tap \+ to create/)` is visible |
| Calendar error | `/calendar` (API mocked to 500) | `getByRole('heading', { name: "Couldn't load events" })` is visible; `getByRole('button', { name: 'Retry' })` is visible |

**Empty-state assertion depth:** each empty state must additionally pass Rule
1 (touch targets on any interactive elements within it) and Rule 2 (no
horizontal overflow).

---

### Rule 6 — Visual Snapshots

**Decision: OMIT `toHaveScreenshot()` assertions entirely for this phase.**

Rationale (from D-08-area steer in 07-CONTEXT.md):
- The Schedule-X calendar widget renders dynamic content (current date
  highlighted, event chips placed by the widget's internal layout engine)
  that will differ between host and CI renderers on different dates and OS
  font-rendering pipelines.
- CI-generated baselines + tolerance configuration (`maxDiffPixelRatio`,
  `threshold`) address pixel variance but not date-dependent layout changes
  (today's date highlight shifts every day; event chip wrapping varies by
  viewport pixel density).
- There is no established prior art in this codebase for non-flaky
  Schedule-X snapshot tests across host↔CI WebKit.
- The structural + role-based locator assertions in Rules 1–5 cover the
  quality bar with zero rendering-pipeline variance.

**If added later:** snapshots must use CI-generated baselines only
(`--update-snapshots` run in the CI environment on first run), store baselines
per browser engine under `apps/pwa/e2e/snapshots/{browser}/`, and set
`maxDiffPixelRatio: 0.03`. Snapshots must be scoped to static UI elements
(e.g. BottomTabBar only, clipped), not the full viewport containing
Schedule-X.

---

### Rule 7 — Auth and Service Worker Preconditions

These are not UI-quality assertions but are preconditions that must hold for
all other assertions to be valid. They are enforced in global-setup and
browser context options.

| Precondition | Enforcement | Source |
|---|---|---|
| `DEV_AUTH_BYPASS=true` in API process | Env var set before dev-server launch | D-01 / Pitfall 14 |
| `serviceWorkers: 'block'` on every context | `playwright.config.ts` contextOptions | D-02 / Pitfall 15 |
| No `storageState` file | `playwright.config.ts` — omit `storageState` | D-01 / Pitfall 14 |
| PWA reachable before specs run | global-setup polls `GET /health` until 200 | D-08 / SC #3 |
| DB fixtures reset before run | global-setup truncate + insert | D-06 |
| No SW-sourced responses | Playwright trace shows no `(ServiceWorker)` source | D-02 / Pitfall 15 |

**SW-source verification (in trace):** after a run, if a test fails with
unexpected data, inspect the `.zip` trace artifact. Any response with source
`(ServiceWorker)` is a contract violation — the `serviceWorkers: 'block'`
option should prevent this. Log a test failure if detected programmatically:

```typescript
// In each test: attach a route listener to flag SW-sourced responses
page.on('response', (resp) => {
  // Playwright does not expose SW-source in the Response object directly;
  // rely on serviceWorkers: 'block' and trace inspection for post-hoc audit.
})
```

---

### Rule 8 — CI Portability

Assertions and harness configuration must produce identical pass/fail results
when run:
1. Locally against the operator's already-running dev stack (Vite PWA +
   API + compose MariaDB/Redis).
2. In Gitea CI against a runner-brought-up dev stack (Phase 8).

**Contract rules:**

| Rule | Enforcement |
|---|---|
| `baseURL` is env-driven (`PLAYWRIGHT_BASE_URL`, fallback `http://localhost:5173`) | `playwright.config.ts` `use.baseURL` |
| No hardcoded `localhost:5173` in spec files | Lint / code review gate |
| Readiness gate in global-setup polls `baseURL + '/health'` until 200 or timeout 60s | `playwright.config.ts` `globalSetup` |
| DB seed uses `DB_HOST` env (fallback `127.0.0.1`), port 3306, same `.env` creds | global-setup `mysql2` connection |
| No spec imports a dev-only module path that does not exist in CI | Jest/Playwright import resolution |
| Browser binaries installed at `apps/pwa` level via `@playwright/test` dep | `apps/pwa/package.json` `devDependencies` |

---

## Checker Sign-Off

> For this phase the checker validates the quality-bar contract dimensions,
> not the standard design-system dimensions.

- [ ] Dimension 1 Copywriting: stable text anchors declared for all empty/error/nav states
- [ ] Dimension 2 Structural: role+name locators declared for all interactive elements
- [ ] Dimension 3 Touch Targets: ≥44px threshold declared with measurement approach
- [ ] Dimension 4 Overflow: `scrollWidth ≤ clientWidth` rule declared with approach
- [ ] Dimension 5 Viewport Matrix: two profiles with correct engines declared (D-03/D-04)
- [ ] Dimension 6 Registry Safety: N/A — `@playwright/test` is official, no vetting required

**Approval:** pending

---

## Source Decisions

| Decision | Source |
|---|---|
| D-01 DEV_AUTH_BYPASS, no storage-state | 07-CONTEXT.md |
| D-02 serviceWorkers: 'block' | 07-CONTEXT.md |
| D-03 iPhone + Pixel two-profile matrix | 07-CONTEXT.md |
| D-04 WebKit for iPhone, Chromium for Pixel | 07-CONTEXT.md |
| D-05 hybrid seed strategy | 07-CONTEXT.md |
| D-06 deterministic reset-per-run seed | 07-CONTEXT.md |
| D-07 global-setup for seeding | 07-CONTEXT.md |
| D-08 readiness gate + configurable baseURL | 07-CONTEXT.md |
| D-09 stack lifecycle is caller's responsibility | 07-CONTEXT.md |
| D-10 optional webServer for Vite | 07-CONTEXT.md |
| 44px threshold | Apple HIG; WCAG 2.5.5; existing codebase pattern |
| Screenshot omission | D-08-area steer; Schedule-X drift risk; 07-CONTEXT.md |
| Pitfall 14 (storage-state stale) | PITFALLS.md §Pitfall 14 |
| Pitfall 15 (SW intercept) | PITFALLS.md §Pitfall 15 |
| Existing tokens/copy strings | `tokens.css`, `EmptyState.tsx`, `ListsEmptyState.tsx`, `CalendarShell.tsx`, `AppNav.tsx`, `BottomTabBar.tsx` |