Phase 8: Gitea CI — runner probe + PR gating jobs (fast-checks + api) #3
@@ -62,7 +62,7 @@ Make FamilySync configurable, administrable, and maintainable for real multi-mem
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
|
||||
- [ ] 07-02-PLAN.md — global-setup.ts: /health readiness poll + deterministic mysql2 reset-and-seed (calendar id 10 INSERT IGNORE guard, list + items) + e2e README/guardrails (Wave 2)
|
||||
- [x] 07-02-PLAN.md — global-setup.ts: /health readiness poll + deterministic mysql2 reset-and-seed (calendar id 10 INSERT IGNORE guard, list + items) + e2e README/guardrails (Wave 2)
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
|
||||
@@ -200,7 +200,7 @@ Make FamilySync configurable, administrable, and maintainable for real multi-mem
|
||||
| 4. Shared Lists + Live Sync | v1.0 | 7/7 | Complete | 2026-06-09 |
|
||||
| 5. Web Push Notifications | v1.0 | 8/8 | Complete | 2026-06-10 |
|
||||
| 6. UX Polish | v1.0 | 6/6 | Complete | 2026-06-10 |
|
||||
| 7. Mobile Test Harness | v1.1 | 1/4 | In Progress| |
|
||||
| 7. Mobile Test Harness | v1.1 | 2/4 | In Progress| |
|
||||
| 8. Gitea CI | v1.1 | 0/? | Not started | - |
|
||||
| 9. Faster Write-Back | v1.1 | 0/? | Not started | - |
|
||||
| 10. Admin Role & Settings | v1.1 | 0/? | Not started | - |
|
||||
@@ -213,7 +213,7 @@ Make FamilySync configurable, administrable, and maintainable for real multi-mem
|
||||
|
||||
**Goal:** [Captured for future planning] Abstract the calendar backend behind a provider interface so Fastmail/CalDAV is one implementation among potentially many. Shipping with a single provider is fine, but the broker, sync, and event-expansion layers should be structured so additional providers (e.g. other CalDAV hosts, Google Calendar, generic ICS feeds) can be added without rework. Captures the "provider" seam as an explicit architectural concern.
|
||||
**Requirements:** TBD
|
||||
**Plans:** 1/4 plans executed
|
||||
**Plans:** 2/4 plans executed
|
||||
|
||||
Plans:
|
||||
|
||||
|
||||
+5
-4
@@ -4,13 +4,13 @@ milestone: v1.1
|
||||
milestone_name: Operability & Polish
|
||||
status: executing
|
||||
stopped_at: Phase 7 UI-SPEC approved
|
||||
last_updated: "2026-06-11T05:45:34.368Z"
|
||||
last_updated: "2026-06-11T05:52:57.489Z"
|
||||
last_activity: 2026-06-11 -- Phase 07 execution started
|
||||
progress:
|
||||
total_phases: 14
|
||||
completed_phases: 0
|
||||
total_plans: 4
|
||||
completed_plans: 1
|
||||
completed_plans: 2
|
||||
percent: 0
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-06-10)
|
||||
## Current Position
|
||||
|
||||
Phase: 07 (mobile-test-harness) — EXECUTING
|
||||
Plan: 2 of 4
|
||||
Plan: 3 of 4
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-06-11 -- Phase 07 execution started
|
||||
|
||||
@@ -78,6 +78,7 @@ Last activity: 2026-06-11 -- Phase 07 execution started
|
||||
| Phase 06-ux-polish P05 | 35 | 4 tasks | 6 files |
|
||||
| Phase 06-ux-polish P06 | 45 | 4 tasks | 5 files |
|
||||
| Phase 07 P01 | 310 | 3 tasks | 7 files |
|
||||
| Phase 07 P02 | 196 | 2 tasks | 4 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -185,7 +186,7 @@ Recent decisions affecting current work:
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-06-11T05:45:34.358Z
|
||||
Last session: 2026-06-11T05:52:57.479Z
|
||||
Stopped at: Phase 7 UI-SPEC approved
|
||||
Resume file: .planning/phases/07-mobile-test-harness/07-UI-SPEC.md
|
||||
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
phase: 07-mobile-test-harness
|
||||
plan: "02"
|
||||
subsystem: test-harness
|
||||
tags: [playwright, e2e, global-setup, db-seed, mysql2, readiness-gate]
|
||||
dependency_graph:
|
||||
requires:
|
||||
- "apps/pwa/playwright.config.ts (07-01) — globalSetup path reference"
|
||||
- "apps/api dev MariaDB :3306 — seed target"
|
||||
- "apps/api DEV_AUTH_BYPASS=true — required in API process before harness runs"
|
||||
provides:
|
||||
- "global-setup.ts — /health readiness poll + deterministic reset-and-seed"
|
||||
- "e2e/README.md — run instructions and security guardrails"
|
||||
- "mysql2@3.22.4 devDependency in apps/pwa"
|
||||
affects:
|
||||
- "Phase 07 plans 03-04 (specs depend on this seed for populated-state assertions)"
|
||||
- "Phase 08 CI (globalSetup runs unchanged in the CI runner)"
|
||||
tech_stack:
|
||||
added:
|
||||
- "mysql2@3.22.4 devDependency in apps/pwa — enables mysql2/promise in global-setup.ts"
|
||||
patterns:
|
||||
- "TRUNCATE + INSERT (not INSERT IGNORE) for seed rows — D-06 deterministic reset"
|
||||
- "INSERT IGNORE INTO calendars guard — ensures calendar_id=10 FK satisfied on fresh CI DB (Pitfall 4)"
|
||||
- "SET FOREIGN_KEY_CHECKS=0/1 around TRUNCATE — FK-safe truncate ordering"
|
||||
- "fetch() for /health poll — native Node.js 22, no @playwright/test import (Pitfall 2)"
|
||||
key_files:
|
||||
created:
|
||||
- apps/pwa/e2e/README.md
|
||||
modified:
|
||||
- apps/pwa/e2e/global-setup.ts
|
||||
- apps/pwa/package.json
|
||||
- pnpm-lock.yaml
|
||||
decisions:
|
||||
- "D-07-02-mysql2-in-pwa: Added mysql2@3.22.4 as devDependency to apps/pwa — global-setup.ts needs mysql2/promise for TypeScript types; the package was already in the monorepo (apps/api), so pnpm install just linked it without downloading"
|
||||
- "D-07-02-deadline-check: Added explicit deadline check after the health poll loop to distinguish 'loop exited via break (success)' from 'loop exited via deadline expiry' — ensures throw fires correctly on timeout"
|
||||
- "D-07-02-dtend-in-vevent: Added DTEND line to the minimal VCALENDAR seed string for spec compatibility — some CalDAV parsers reject VEVENTs without DTEND"
|
||||
metrics:
|
||||
duration_seconds: 196
|
||||
completed_date: "2026-06-11"
|
||||
tasks_completed: 2
|
||||
files_changed: 4
|
||||
---
|
||||
|
||||
# Phase 07 Plan 02: globalSetup Readiness Gate + DB Seed Summary
|
||||
|
||||
**One-liner:** Playwright globalSetup with 60s /health readiness poll and deterministic TRUNCATE+INSERT seed onto calendar_id=10 and user_id=1 lists — idempotent run-over-run.
|
||||
|
||||
## What Was Built
|
||||
|
||||
- `apps/pwa/e2e/global-setup.ts` — full implementation replacing the Plan 01 stub:
|
||||
- Step 1 (D-08): polls `${PLAYWRIGHT_BASE_URL}/health` with a 60-second deadline; swallows ECONNREFUSED; breaks on first `res.ok`; throws with a clear diagnostic message if the deadline passes
|
||||
- Step 2 (D-06/D-07): direct mysql2 connection using exact env-var names from `apps/api/src/db/client.ts`; `SET FOREIGN_KEY_CHECKS=0` → TRUNCATE list_items/list_shares/lists/calendar_events → `SET FOREIGN_KEY_CHECKS=1` → INSERT IGNORE calendars guard (id=10) → one timed calendar_event → E2E Grocery List (owner_id=1, is_shared=true) + list_shares row + Milk/Eggs items
|
||||
- No `@playwright/test` imports — plain Node.js (Pitfall 2 compliant)
|
||||
|
||||
- `apps/pwa/e2e/README.md` — operator reference documenting:
|
||||
- Prerequisites: dev stack (API + PWA + MariaDB + Redis) with DEV_AUTH_BYPASS=true
|
||||
- Run commands: `pnpm --filter @familysync/pwa test:e2e`, single profile, headed, UI mode
|
||||
- Env var contract: PLAYWRIGHT_BASE_URL, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME — credentials env-only, never hardcoded (T-07-05)
|
||||
- Security guardrail: DEV_AUTH_BYPASS is dev-only, NODE_ENV !== 'production' hard guard, production compose MUST NOT set it (T-07-04)
|
||||
- No storageState (D-01 — designed out)
|
||||
- CI scope note: Phase 8 brings up the stack; harness handles its own readiness gate
|
||||
|
||||
- `apps/pwa/package.json` — mysql2@3.22.4 added as devDependency (same version as apps/api; pnpm linked without downloading)
|
||||
|
||||
## Verification Evidence
|
||||
|
||||
- `grep "^import mysql from 'mysql2/promise'" apps/pwa/e2e/global-setup.ts` — found
|
||||
- `grep "from '@playwright/test'" apps/pwa/e2e/global-setup.ts` — absent (Pitfall 2 pass)
|
||||
- `grep "TRUNCATE TABLE" apps/pwa/e2e/global-setup.ts` — 4 tables (list_items, list_shares, lists, calendar_events)
|
||||
- `grep "INSERT IGNORE INTO calendars" apps/pwa/e2e/global-setup.ts` — found with VALUES (10, 1, ...)
|
||||
- `grep "list_shares\|Milk\|Eggs" apps/pwa/e2e/global-setup.ts` — all present
|
||||
- `grep -c 'DEV_AUTH_BYPASS|NODE_ENV|storageState|PLAYWRIGHT_BASE_URL|test:e2e' apps/pwa/e2e/README.md` → 15 (acceptance criteria: non-zero count)
|
||||
- `tsc --noEmit --project tsconfig.e2e.json` (apps/pwa) → 0 errors
|
||||
- `tsc --noEmit` (apps/pwa src) → 0 errors
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] mysql2 not available in apps/pwa**
|
||||
- **Found during:** Task 1 TypeScript check — `tsc --noEmit --project tsconfig.e2e.json` emitted `TS2307: Cannot find module 'mysql2/promise'`
|
||||
- **Issue:** mysql2 is in `apps/api/dependencies` but not linked to `apps/pwa`. The global-setup imports `mysql2/promise` which requires the package to be a direct or devDependency of apps/pwa for TypeScript resolution.
|
||||
- **Fix:** Added `"mysql2": "3.22.4"` to `apps/pwa/devDependencies` (same version as apps/api to stay in sync). `pnpm install` linked it from the pnpm store in 4s with zero downloads — the binary was already present from apps/api.
|
||||
- **Files modified:** `apps/pwa/package.json`, `pnpm-lock.yaml`
|
||||
- **Commit:** 53498e3
|
||||
|
||||
**2. [Rule 2 - Missing Critical] Explicit deadline-exceeded throw after poll loop**
|
||||
- **Found during:** Task 1 implementation review — the research pattern's while loop exits via `break` on success OR when `Date.now() >= deadline`. After the loop, without an explicit check, code would silently proceed to the DB seed on a timed-out poll, causing confusing mysql2 errors rather than a clear "stack is not up" message.
|
||||
- **Fix:** Added `if (Date.now() >= deadline) { throw new Error(...) }` immediately after the while loop so timeout is distinguishable from success.
|
||||
- **Files modified:** `apps/pwa/e2e/global-setup.ts`
|
||||
- **Commit:** 53498e3
|
||||
|
||||
**3. [Rule 2 - Missing Critical] DTEND in minimal VCALENDAR seed string**
|
||||
- **Found during:** Task 1 implementation — minimal VCALENDAR without DTEND may fail CalDAV/ical.js parsing in some spec paths. Plan said "minimal VCALENDAR/VEVENT" but no explicit DTEND.
|
||||
- **Fix:** Added DTEND line (futureStart + 1 hour) to the VCALENDAR seed string for spec compatibility. Does not affect seed idempotency.
|
||||
- **Files modified:** `apps/pwa/e2e/global-setup.ts`
|
||||
- **Commit:** 53498e3
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — the Plan 01 stub in global-setup.ts is fully replaced with the real implementation.
|
||||
|
||||
## Threat Surface Scan
|
||||
|
||||
No new network endpoints, auth paths, or schema changes. All changes are test-infrastructure files only.
|
||||
|
||||
Threat mitigations from plan threat model:
|
||||
- **T-07-04 (Elevation of Privilege / DEV_AUTH_BYPASS):** README explicitly documents that DEV_AUTH_BYPASS is dev-only, that the API guards on `NODE_ENV !== 'production'`, and that the production compose MUST NOT set it. global-setup does not set the env var (it cannot — it runs after the API is already up).
|
||||
- **T-07-05 (Information Disclosure / DB credentials):** global-setup reads DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_NAME from env exclusively, mirroring `apps/api/src/db/client.ts`. No credential is hardcoded. README states this explicitly.
|
||||
- **T-07-06 (Information Disclosure / OIDC session state):** No storageState.json is written by the harness. README states this. Designed out per D-01.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- `apps/pwa/e2e/global-setup.ts` — exists
|
||||
- `apps/pwa/e2e/README.md` — exists
|
||||
- Task 1 commit `53498e3` — exists
|
||||
- Task 2 commit `535ba11` — exists
|
||||
@@ -0,0 +1,477 @@
|
||||
# Phase 7: Mobile Test Harness — Pattern Map
|
||||
|
||||
**Mapped:** 2026-06-10
|
||||
**Files analyzed:** 7 (5 new, 2 modified)
|
||||
**Analogs found:** 7 / 7
|
||||
|
||||
---
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
||||
|---|---|---|---|---|
|
||||
| `apps/pwa/playwright.config.ts` | config | request-response | `apps/pwa/vitest.config.ts` + `apps/api/vitest.config.ts` | role-match (same config-file shape, different runner) |
|
||||
| `apps/pwa/e2e/global-setup.ts` | utility | CRUD (DB seed + HTTP poll) | `apps/api/src/db/client.ts` (mysql2 connection) + `apps/api/tests/routes/lists.test.ts` (seed helpers) | partial-match (same DB driver + env-var pattern) |
|
||||
| `apps/pwa/e2e/layout.spec.ts` | test | request-response | `apps/pwa/src/components/CalendarShell.test.tsx` (role/name locators, screen queries) | role-match |
|
||||
| `apps/pwa/e2e/calendar.spec.ts` | test | request-response | `apps/pwa/src/components/CalendarShell.test.tsx` | role-match |
|
||||
| `apps/pwa/e2e/lists.spec.ts` | test | request-response | `apps/pwa/src/routes/ListDetail.test.tsx` | role-match |
|
||||
| `apps/pwa/vitest.config.ts` *(modify)* | config | — | `apps/pwa/vitest.config.ts` (self — add `exclude`) | exact |
|
||||
| `apps/pwa/package.json` *(modify)* | config | — | `apps/pwa/package.json` (self) + root `package.json` (script conventions) | exact |
|
||||
|
||||
---
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### `apps/pwa/playwright.config.ts` (config, new)
|
||||
|
||||
**Analog:** `apps/pwa/vitest.config.ts` (lines 1–14) — `defineConfig` wrapper convention; and `apps/api/vitest.config.ts` (lines 1–14) — `fileParallelism: false` and `setupFiles` equivalents.
|
||||
|
||||
**Config structure pattern** (`apps/pwa/vitest.config.ts`, lines 1–14):
|
||||
```typescript
|
||||
import { defineConfig } from 'vitest/config'
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
globals: true,
|
||||
setupFiles: ['./src/test-setup.ts'],
|
||||
env: { TZ: 'UTC' },
|
||||
},
|
||||
})
|
||||
```
|
||||
Key observation: no explicit `include` — Vitest defaults catch `*.spec.ts` too, which is why `exclude` must be added.
|
||||
|
||||
**Serial execution pattern** (`apps/api/vitest.config.ts`, lines 1–14):
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'node',
|
||||
globals: true,
|
||||
setupFiles: ['./test/setup.ts'],
|
||||
fileParallelism: false, // ← serial DB tests; analogous to workers:1 in CI
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**Playwright config shape to produce** (from RESEARCH.md Architecture Patterns §Pattern 1):
|
||||
```typescript
|
||||
// apps/pwa/playwright.config.ts
|
||||
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', // D-02 / Pitfall 15
|
||||
},
|
||||
},
|
||||
{
|
||||
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, // D-10
|
||||
timeout: 120_000,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/e2e/global-setup.ts` (utility, new)
|
||||
|
||||
**Analog 1 — mysql2 connection env-var pattern:** `apps/api/src/db/client.ts` (lines 1–16)
|
||||
|
||||
```typescript
|
||||
// apps/api/src/db/client.ts lines 6-14 — exact env-var names to copy
|
||||
const pool = mysql.createPool({
|
||||
host: process.env.DB_HOST ?? 'localhost',
|
||||
port: Number(process.env.DB_PORT ?? 3306),
|
||||
user: process.env.DB_USER ?? 'familysync',
|
||||
password: process.env.DB_PASSWORD ?? '',
|
||||
database: process.env.DB_NAME ?? 'familysync',
|
||||
waitForConnections: true,
|
||||
connectionLimit: 10,
|
||||
})
|
||||
```
|
||||
The global-setup uses `mysql.createConnection` (single connection, not pool) with identical env-var names. `DB_HOST` defaults to `127.0.0.1` (not `localhost`) per project memory `api-integration-test-db`.
|
||||
|
||||
**Analog 2 — seed helper pattern:** `apps/api/tests/routes/lists.test.ts` (lines 50–85) — shows Drizzle-based seed helpers. The global-setup uses raw `mysql2` instead (no Drizzle outside API), but the INSERT shape and table names are confirmed here:
|
||||
- `lists`: `(owner_id, name, is_shared)` — `ownerId=1`, `isShared=true`
|
||||
- `list_shares`: `(list_id, user_id)` — join table, seed one row for user 1
|
||||
- `list_items`: `(list_id, text, checked, rank)` — `rank` is fractional-indexing string (e.g. `'a0'`, `'a1'`)
|
||||
|
||||
**Schema column names** (confirmed from `apps/api/src/db/schema.ts`):
|
||||
|
||||
| Table | Relevant columns |
|
||||
|---|---|
|
||||
| `calendars` | `id`, `user_id`, `url`, `display_name`, `color`, `is_shared` |
|
||||
| `calendar_events` | `calendar_id`, `uid`, `etag`, `raw_vevent`, `title`, `dtstart_utc` (TIMESTAMP), `dtstart_date` (DATE), `all_day`, `has_rrule` |
|
||||
| `lists` | `id`, `owner_id`, `name`, `is_shared` |
|
||||
| `list_shares` | `list_id`, `user_id` |
|
||||
| `list_items` | `list_id`, `text`, `checked`, `rank` (utf8mb4_bin varchar) |
|
||||
|
||||
**DEV_USER confirmed** (`apps/api/src/auth/devBypass.ts`, lines 30–36):
|
||||
```typescript
|
||||
export const DEV_USER = {
|
||||
id: 1,
|
||||
oidcIss: 'dev',
|
||||
oidcSub: 'dev-user',
|
||||
displayName: 'Dev User',
|
||||
color: '#4A90D9',
|
||||
} as const
|
||||
```
|
||||
Seeds must target `user_id = 1` and `owner_id = 1`.
|
||||
|
||||
**Guard for production** (`apps/api/src/auth/devBypass.ts`, lines 61–66):
|
||||
```typescript
|
||||
if (process.env.NODE_ENV === 'production') {
|
||||
return async (_c, next) => next()
|
||||
}
|
||||
if (process.env.DEV_AUTH_BYPASS !== 'true') {
|
||||
return async (_c, next) => next()
|
||||
}
|
||||
```
|
||||
The bypass requires both `NODE_ENV !== 'production'` AND `DEV_AUTH_BYPASS=true`. The harness does not control these; they must be set before the API process starts.
|
||||
|
||||
**Full global-setup shape** (from RESEARCH.md §Pattern 2):
|
||||
```typescript
|
||||
// apps/pwa/e2e/global-setup.ts
|
||||
import mysql from 'mysql2/promise'
|
||||
|
||||
export default async function globalSetup() {
|
||||
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 */ }
|
||||
await new Promise((r) => setTimeout(r, 1_000))
|
||||
}
|
||||
|
||||
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 {
|
||||
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')
|
||||
|
||||
// CI guard: ensure calendars row id=10 exists (Pitfall 4)
|
||||
await conn.execute(
|
||||
`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)`
|
||||
)
|
||||
|
||||
// Seed one timed calendar event on shared calendar id=10
|
||||
const uid = 'e2e-seed-event-001'
|
||||
const futureStart = new Date(Date.now() + 24 * 60 * 60 * 1000)
|
||||
const futureStartUtc = futureStart.toISOString().replace(/\.\d+Z$/, 'Z')
|
||||
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 as any).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()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/e2e/layout.spec.ts` (test, new)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/CalendarShell.test.tsx` — the closest existing file using `screen.findByRole`, `getByRole`, and `waitFor` patterns with role/name locator assertions.
|
||||
|
||||
**Test file structure** (`CalendarShell.test.tsx`, lines 14–18, 140–158):
|
||||
```typescript
|
||||
import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest'
|
||||
// ...
|
||||
describe('CalendarShell — CAL-03 render smoke', () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks()
|
||||
sessionStorage.clear()
|
||||
})
|
||||
it('renders without throwing...', () => { ... })
|
||||
it('mounts the ScheduleXCalendar...', async () => { ... })
|
||||
})
|
||||
```
|
||||
|
||||
**Role-based locator pattern** (`CalendarShell.test.tsx`, lines 220–230):
|
||||
```typescript
|
||||
const tapToRetry = await screen.findByText(/Tap here to try again/i)
|
||||
expect(tapToRetry).toBeDefined()
|
||||
```
|
||||
|
||||
**Playwright equivalents** (from RESEARCH.md §Patterns 3–5) — `@playwright/test` uses `page.getByRole()`, not `screen`:
|
||||
```typescript
|
||||
import { test, expect } from '@playwright/test'
|
||||
|
||||
test.describe('BottomTabBar presence and tap targets', () => {
|
||||
test.beforeEach(async ({ page }) => { await page.goto('/calendar') })
|
||||
|
||||
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)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
**Error state via `page.route()`** (from RESEARCH.md §Pattern 5):
|
||||
```typescript
|
||||
// Register BEFORE page.goto() — route intercepts the matching request
|
||||
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()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/e2e/calendar.spec.ts` (test, new)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/CalendarShell.test.tsx` — same component under test; provides fixture data shapes and the expected ARIA landmark (`data-testid="schedule-x-calendar"`, navigation role).
|
||||
|
||||
**Fixture data shape confirmed** (`CalendarShell.test.tsx`, lines 83–113):
|
||||
```typescript
|
||||
// Timed event shape returned by /api/events
|
||||
const TIMED_OCCURRENCE = {
|
||||
id: 'timed-uid::2026-06-15T10:00:00',
|
||||
title: 'Team Standup',
|
||||
start: '2026-06-15T10:00:00-04:00[America/New_York]',
|
||||
end: '2026-06-15T10:30:00-04:00[America/New_York]',
|
||||
allDay: false,
|
||||
}
|
||||
```
|
||||
|
||||
**Key insight:** The Playwright spec navigates to `/calendar` and asserts structural elements (Schedule-X wrapper present and visible, event chip text visible for seeded event) via role/text locators — not by data-testid (prefer stable ARIA roles). The seeded event title is `'Seeded Test Event'`.
|
||||
|
||||
**Query client wrapper convention** (`CalendarShell.test.tsx`, lines 117–136) — not directly applicable in Playwright (no React wrapper needed), but confirms the route path is `/calendar`.
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/e2e/lists.spec.ts` (test, new)
|
||||
|
||||
**Analog:** `apps/pwa/src/routes/ListDetail.test.tsx` — the closest file testing the lists data shape; confirms list item text (`'bread'`, `'Milk'`, `'Eggs'`), the two-section layout (active / completed), and the `rank` fractional-indexing strings.
|
||||
|
||||
**List item shape** (`ListDetail.test.tsx`, lines 21–31):
|
||||
```typescript
|
||||
function makeItem(overrides: Partial<ListItem> = {}): ListItem {
|
||||
return {
|
||||
id: 1,
|
||||
listId: 10,
|
||||
text: 'bread',
|
||||
checked: false,
|
||||
rank: 'a0',
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Section assertion pattern** (`ListDetail.test.tsx`, lines 178–193):
|
||||
```typescript
|
||||
const activeItems = items.filter((i) => !i.checked)
|
||||
const completedItems = items.filter((i) => i.checked)
|
||||
expect(activeItems).toHaveLength(1)
|
||||
expect(completedItems).toHaveLength(1)
|
||||
```
|
||||
|
||||
In Playwright: assert `page.getByRole('listitem', { name: 'Milk' })` is visible (seeded active item) and that the "No items yet" empty text is NOT visible when seeded.
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/vitest.config.ts` *(modify)*
|
||||
|
||||
**Analog:** Self — read at lines 1–14 above. Change is additive: add `exclude` array to prevent Vitest from picking up `e2e/**/*.spec.ts`.
|
||||
|
||||
**Current file** (`apps/pwa/vitest.config.ts`, lines 1–14):
|
||||
```typescript
|
||||
import { defineConfig } from 'vitest/config'
|
||||
|
||||
export default defineConfig({
|
||||
test: {
|
||||
environment: 'jsdom',
|
||||
globals: true,
|
||||
setupFiles: ['./src/test-setup.ts'],
|
||||
env: { TZ: 'UTC' },
|
||||
// ADD: exclude to prevent Vitest glob collision with Playwright specs
|
||||
// exclude: ['e2e/**', 'node_modules/**'],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**Diff to apply:** add one line inside the `test:` block:
|
||||
```typescript
|
||||
exclude: ['e2e/**', 'node_modules/**'],
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/package.json` *(modify)*
|
||||
|
||||
**Analog:** `apps/pwa/package.json` (self, lines 6–11) + root `package.json` (lines 4–12) for naming conventions.
|
||||
|
||||
**Current scripts block** (`apps/pwa/package.json`, lines 6–11):
|
||||
```json
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "tsc && vite build",
|
||||
"preview": "vite preview",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"test": "vitest run"
|
||||
}
|
||||
```
|
||||
|
||||
**Root workspace convention** (`package.json`, lines 4–12): scripts use `pnpm --filter @familysync/<app> <script>` and follow `verb` or `verb:modifier` naming (`dev:api`, `dev:pwa`, `typecheck`).
|
||||
|
||||
**Additions to `apps/pwa/package.json`:**
|
||||
```json
|
||||
"test:e2e": "playwright test",
|
||||
"test:e2e:ui": "playwright test --ui",
|
||||
"test:e2e:headed": "playwright test --headed"
|
||||
```
|
||||
|
||||
**Addition to `devDependencies`:**
|
||||
```json
|
||||
"@playwright/test": "1.60.0"
|
||||
```
|
||||
|
||||
**Root `package.json` addition** (propagate to workspace-level scripts):
|
||||
```json
|
||||
"test:e2e": "pnpm --filter @familysync/pwa test:e2e"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Dev bypass — resolves to user id 1
|
||||
**Source:** `apps/api/src/auth/devBypass.ts` lines 30–36, 61–76
|
||||
**Apply to:** `global-setup.ts` (seed targets `user_id=1`, `owner_id=1`); all spec files (asserted data belongs to user 1)
|
||||
```typescript
|
||||
// DEV_USER.id === 1 — seed and assert against this identity
|
||||
export const DEV_USER = { id: 1, displayName: 'Dev User', color: '#4A90D9' } as const
|
||||
// Guard: requires NODE_ENV !== 'production' AND DEV_AUTH_BYPASS=true
|
||||
```
|
||||
|
||||
### mysql2 env-var connection pattern
|
||||
**Source:** `apps/api/src/db/client.ts` lines 6–14
|
||||
**Apply to:** `global-setup.ts`
|
||||
```typescript
|
||||
// Exact env-var names used across the project — use same names in global-setup
|
||||
host: process.env.DB_HOST ?? '127.0.0.1', // NOT 'localhost' (per memory api-integration-test-db)
|
||||
port: Number(process.env.DB_PORT ?? 3306),
|
||||
user: process.env.DB_USER ?? 'familysync',
|
||||
password: process.env.DB_PASSWORD ?? '',
|
||||
database: process.env.DB_NAME ?? 'familysync',
|
||||
```
|
||||
|
||||
### Test file header comment convention
|
||||
**Source:** `apps/pwa/src/components/CalendarShell.test.tsx` lines 1–14; `apps/api/tests/routes/lists.test.ts` lines 1–17
|
||||
**Apply to:** all `e2e/*.spec.ts` files and `global-setup.ts`
|
||||
```typescript
|
||||
/**
|
||||
* <Component/route> — <requirement ID>
|
||||
*
|
||||
* <what it tests>
|
||||
*
|
||||
* Run:
|
||||
* pnpm --filter @familysync/pwa test:e2e
|
||||
*/
|
||||
```
|
||||
|
||||
### Role/name locator convention (Vitest + Testing Library → Playwright equivalent)
|
||||
**Source:** `apps/pwa/src/components/CalendarShell.test.tsx` lines 217–231
|
||||
```typescript
|
||||
// Testing Library (Vitest) — existing pattern
|
||||
const tapToRetry = await screen.findByText(/Tap here to try again/i)
|
||||
// ↓ Playwright equivalent in e2e specs:
|
||||
await expect(page.getByRole('button', { name: /Retry/i })).toBeVisible()
|
||||
await expect(page.getByText(/Tap here to try again/i)).toBeVisible()
|
||||
```
|
||||
|
||||
### No hardcoded absolute URLs in specs
|
||||
**Source:** RESEARCH.md §Anti-Patterns; consistent with `apps/pwa/vite.config.ts` proxy pattern
|
||||
**Apply to:** all `e2e/*.spec.ts` files
|
||||
```typescript
|
||||
// Wrong — breaks CI
|
||||
await page.goto('http://localhost:5173/calendar')
|
||||
// Correct — resolves against playwright.config.ts baseURL
|
||||
await page.goto('/calendar')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## No Analog Found
|
||||
|
||||
None. All files have at least a role-match analog in the codebase.
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** `apps/pwa/src/`, `apps/api/src/`, `apps/api/tests/`
|
||||
**Files read:** 12
|
||||
**Pattern extraction date:** 2026-06-10
|
||||
Reference in New Issue
Block a user