docs(14): capture phase context
This commit is contained in:
Lucas Berger
@@ -0,0 +1,151 @@
|
||||
# Phase 14: Desktop E2E Coverage - Context
|
||||
|
||||
**Gathered:** 2026-06-12
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Add a `desktop` Playwright project (Desktop Chrome, wide viewport, no `hasTouch`) to
|
||||
`apps/pwa/playwright.config.ts` and make the existing Phase 7 mobile-authored e2e specs
|
||||
pass on a no-touch desktop viewport, so the Phase 8 CI regression gate validates the
|
||||
**desktop** layout/flows in addition to the `iphone`/`pixel` mobile profiles.
|
||||
|
||||
The real work is the **spec-compat pass**, not CI plumbing — Phase 8 already runs
|
||||
`pnpm test:e2e` and will pick up the new project automatically. No new test *capabilities*
|
||||
are added; this is desktop-profile coverage of the layout/state bars Phase 7 already asserts.
|
||||
|
||||
**In scope:** desktop project config; per-spec review so the suite is green on desktop;
|
||||
desktop-equivalent assertions where the mobile layout diverges.
|
||||
**Out of scope:** new flows/features; live event-create against CalDAV (dev user 1 still has
|
||||
no calendar credential — carried from Phase 7); Desktop WebKit; prod-SW / iOS-standalone testing.
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Spec-Compat Strategy
|
||||
- **D-01:** Keep **one set of spec files** (no separate `desktop.spec.ts`). Gate the genuinely
|
||||
mobile-only tests with `test.skip()` keyed on project name (`desktop`), and add desktop-equivalent
|
||||
assertions where the layout diverges. Cross-cutting tests (no-overflow, populated/empty/error
|
||||
states) stay shared and run on all three profiles. Rationale: one source of truth, least
|
||||
duplication, avoids drift between mobile and desktop copies of the same cross-cutting assertions.
|
||||
- **D-02:** Prefer scoping/skip over deletion — do not weaken or remove the existing mobile
|
||||
assertions to make desktop pass. The mobile profiles must remain exactly as authored in Phase 7.
|
||||
|
||||
### Desktop Gate Severity
|
||||
- **D-03:** Desktop-profile failures are **blocking** — same severity as `iphone`/`pixel`.
|
||||
A desktop regression must not be able to land on `main`. No `continue-on-error` / advisory
|
||||
carve-out. (Resolves ROADMAP Phase 14 Success Criterion 3, which deferred blocking-vs-advisory
|
||||
to planning.) Implication: the desktop specs must be deterministic before this merges —
|
||||
if they flake, fix the spec, don't downgrade the gate.
|
||||
|
||||
### Desktop Assertion Depth
|
||||
- **D-04:** **Parity-adapted** coverage. On desktop, positively assert the desktop equivalents:
|
||||
DesktopNav sidebar (`nav[aria-label="Main navigation"]`) visible, nav tap targets, no horizontal
|
||||
overflow, populated/empty/error states render (calendar grid, seeded event, lists card, empty
|
||||
state, error heading + Retry). Skip only the assertions that have no desktop analog.
|
||||
- **D-05:** Do **not** add "mobile chrome is absent on desktop" negative assertions (the rejected
|
||||
"full divergence" option). Reason grounded in code: the `New Event` accessible name is **not**
|
||||
mobile-only — `CalendarShell.tsx:424` renders a desktop-only toolbar "New Event" button sharing
|
||||
the same name as the phone FAB. Asserting its absence would be wrong. Only the **56×56 FAB
|
||||
geometry** check is mobile-specific.
|
||||
|
||||
### Desktop Profile / Viewport
|
||||
- **D-06:** Single desktop project using `devices['Desktop Chrome']` (1280×720), **no Desktop WebKit**.
|
||||
The Apple member is already covered on mobile Safari via the `iphone`/WebKit profile; Desktop
|
||||
Chrome is sufficient for the shared/wall-browser use case. Keep the default viewport — no custom
|
||||
width override unless planning finds the sidebar layout needs more horizontal room than 1280 gives.
|
||||
|
||||
### Claude's Discretion
|
||||
- Exact mechanism for the skip gate (e.g. `test.skip(testInfo.project.name === 'desktop', ...)` vs.
|
||||
`test.describe` blocks split by a `isDesktop` helper vs. project-level `grep`/`grepInvert`) — pick
|
||||
the cleanest that keeps the shared cross-cutting tests un-duplicated. Planner/researcher to choose.
|
||||
- Whether the desktop "New Event" toolbar button gets its own ≥44px tap-target assertion as the
|
||||
desktop parity equivalent of the FAB's 56×56 check (recommended, but optional).
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### The harness being extended (Phase 7)
|
||||
- `apps/pwa/playwright.config.ts` — the two-profile matrix to extend with a third `desktop` project;
|
||||
documents the carried-forward auth/SW/baseURL/webServer decisions (D-01..D-10 in its header).
|
||||
- `apps/pwa/e2e/layout.spec.ts` — the spec with the most mobile-only assumptions (BottomTabBar
|
||||
safe-area/in-viewport, 56×56 FAB, PhoneNav chrome, tap targets). Primary compat-pass target.
|
||||
- `apps/pwa/e2e/calendar.spec.ts` — auth-bypass precondition, no-SW precondition, populated/error states.
|
||||
- `apps/pwa/e2e/lists.spec.ts` — populated/empty states.
|
||||
- `apps/pwa/e2e/global-setup.ts` — `/health` readiness poll + deterministic DB reset/seed (shared by
|
||||
all profiles, unchanged by this phase).
|
||||
- `apps/pwa/e2e/README.md` — harness run/guardrail docs; update for the new profile.
|
||||
|
||||
### Phase context / roadmap
|
||||
- `.planning/ROADMAP.md` §"Phase 14: Desktop E2E Coverage" — goal, 3 success criteria, pitfalls.
|
||||
- `.planning/phases/07-mobile-test-harness/07-CONTEXT.md` — original harness decisions to carry forward
|
||||
(DEV_AUTH_BYPASS not storageState, `serviceWorkers: 'block'`, env baseURL, Vite-only webServer).
|
||||
- `.planning/phases/08-gitea-ci/08-CONTEXT.md` — how CI runs `pnpm test:e2e`; confirms desktop project
|
||||
is picked up automatically (only watch desktop-profile runtime/wait in CI).
|
||||
|
||||
### CI entry point (no plumbing change expected, but verify)
|
||||
- `.gitea/workflows/ci.yml` — the harness job that runs the Playwright specs; confirm the new desktop
|
||||
project runs and gates without a config change beyond runtime/wait budget.
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- **Existing `playwright.config.ts` project array** — add a third `{ name: 'desktop', use: {
|
||||
...devices['Desktop Chrome'], serviceWorkers: 'block' } }` entry. `serviceWorkers: 'block'`,
|
||||
env baseURL, and the Vite `webServer` are already shared across projects.
|
||||
- **`global-setup.ts`** — DB reset/seed is profile-agnostic; reused unchanged for desktop.
|
||||
|
||||
### Established Patterns
|
||||
- **Breakpoint = 767/768px**, driven by `window.matchMedia('(max-width: 767px)')` in
|
||||
`AppNav.tsx:32`, `BottomTabBar.tsx:24`, `CalendarShell.tsx:75`. Desktop Chrome at 1280px is
|
||||
unambiguously in the desktop branch.
|
||||
- **`getByRole('navigation', { name: 'Main navigation' })`** resolves to the **BottomTabBar** on
|
||||
mobile but the **DesktopNav sidebar** on desktop — same locator, different element, both valid.
|
||||
- **No strict-mode collision on desktop:** `BottomTabBar.tsx:53-57` returns `null` at ≥768px, so the
|
||||
sidebar is the *sole* `Main navigation` landmark on desktop. Most nav-visibility/tap-target tests
|
||||
pass as-authored, just resolving to the sidebar.
|
||||
|
||||
### Integration Points — desktop divergences the compat pass must handle
|
||||
- **BottomTabBar safe-area / "fully in-viewport" tests** (`layout.spec.ts` describe blocks):
|
||||
bottom bar is `null` on desktop → **skip on desktop**.
|
||||
- **"New Event FAB meets 56×56px"** (`layout.spec.ts:91`): on desktop the `New Event` name resolves
|
||||
to the toolbar button (`CalendarShell.tsx:424`), which is not 56×56 → **skip the FAB-geometry test
|
||||
on desktop**; optionally assert the desktop toolbar button's ≥44px target instead (D-04 parity).
|
||||
- **"PhoneNav header is visible"** (`layout.spec.ts:76`): `getByText('FamilySync', {exact:true})` also
|
||||
matches the DesktopNav title (`AppNav.tsx:181`) → likely passes on desktop; verify no second match.
|
||||
- **Settings button** (`/open settings/i`): present on both PhoneNav and DesktopNav → resolves on both.
|
||||
- **Tap-target tests scoped to the nav landmark**: desktop sidebar links have `minHeight: 44px`
|
||||
(`AppNav.tsx:151`) → pass on desktop.
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The gate's whole point is to be real: desktop must be **blocking**, and the specs must be made
|
||||
deterministic to earn that (D-03). "Make it green by weakening the assertion" is explicitly rejected.
|
||||
- Mirror Phase 7's self-validation ethos where cheap: a desktop run should fail loudly if the desktop
|
||||
layout actually regresses, not silently pass because everything was skipped.
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- **Desktop WebKit (Desktop Safari) profile** — considered and declined for this phase (D-06).
|
||||
Revisit only if a desktop-Safari-specific rendering bug is ever reported.
|
||||
- **Live desktop event-create round-trip** — still blocked by dev user 1 having no CalDAV calendar
|
||||
(carried from Phase 7); out of scope here, same as on mobile.
|
||||
|
||||
None of the above are blockers — discussion stayed within phase scope.
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 14-Desktop E2E Coverage*
|
||||
*Context gathered: 2026-06-12*
|
||||
Reference in New Issue
Block a user