Test Plan

How CivicLoop County OS is tested. Tests verify real behavior (forms save, data is visible, actions persist, no JS errors), never just "page loaded".

Layers

1. Unit + feature (Playwright): cd web && npm test. ~53 specs across smoke (db-integrity, page-scan), feature (auth/mfa/console/dashboard/track/report-flow/admin/notifications/close-flow/voice-intake/duplicate/ai-insights/open311), journey (hero-flow, i18n round-trips, open311 round-trip), cross-cutting (RBAC), and mobile viewport. tests/helpers.ts has loginAsStaff().
2. Every-button per-role UI sweep: node scripts/ui-sweep.mjs. Logs in as each role (supervisor, director, admin), visits every page including all County OS modules, /feeds, /assistant, and the public portals, clicks every SAFE button, and FAILS on any uncaught JS error. This is the regression test for client-reference / server-component crashes (the class of bug that produces a blank error boundary). Destructive/navigating buttons are deny-listed; dialogs auto-dismiss.
3. Production smoke: node scripts/prod-smoke.mjs. 20 checks across the app, docs site, and Open311 endpoints. Run before any dress rehearsal and after every deploy.
4. Recorded-UI demo as QA: node scripts/record-demo.mjs produces a silent, caption-burned .webm walking all roles + modules; a clean run is a QA pass.
5. Voiced walkthrough render: node scripts/make-walkthrough-video.mjs doubles as an end-to-end smoke (it logs in and tours every surface) while producing the sales videos.

What "green" means

• npm run build exits 0 (compile + lint + types).
• node scripts/ui-sweep.mjs reports 0 errors across all roles and pages.
• node scripts/prod-smoke.mjs all checks pass.

Conventions

• Idempotent: tests clean up after themselves (DELETE /api/test-verify?...).
• MFA-aware: the MFA spec uses a dedicated account and the live 30-second TOTP window.
• Never guess columns: check information_schema (or the schema dump) before asserting on DB shape.
• No .test-TLD accounts on production. Demo staff use @pgc.example.gov.

Test accounts (demo)

agent@, supervisor@, director@, admin@, mfatest@pgc.example.gov - password in TEST_COUNTY_SETUP.md. Do not reuse the reserved test phone numbers listed there for new tests.

Known flakes

• MFA spec depends on the 30-second TOTP window; passes in isolation.
• Long full-suite runs can hit transient ERR_CONNECTION_RESET on the dev server; re-run the affected spec.
• The UI sweep waits on networkidle; the dashboard's auto-refresh can delay it (45s timeout, then continues).