docs(07-02): complete globalSetup seed plan
This commit is contained in:
Lucas Berger
@@ -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