docs: frontend testing plan (Playwright + Vitest)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/frontend-testing-plan.md

@@ -0,0 +1,155 @@
+# Frontend Testing Plan
+
+## Overview
+
+The admin frontend has grown significantly (station mode, POS, repairs intake, lessons). We need frontend testing to catch regressions and validate critical user flows.
+
+## Recommended Stack
+
+### Tier 1: Playwright (E2E)
+**Priority: High — implement first**
+
+End-to-end browser tests that exercise the full app against a running backend. Catches integration issues, routing problems, and real user flow regressions.
+
+- **Framework:** Playwright (`@playwright/test`)
+- **Runner:** `bun run test:e2e` (or `npx playwright test`)
+- **Location:** `packages/admin/e2e/`
+- **CI:** Runs in the `e2e` job alongside API tests (needs backend + DB + Valkey)
+
+#### Critical flows to test first
+1. **Login flow** — email/password login, redirect to dashboard, logout
+2. **Forgot password** — submit email, see success message
+3. **Station PIN login** — navigate to /station, enter PIN, unlock, see tabs
+4. **Station tab switching** — POS → Repairs → Lessons, verify content renders
+5. **POS sale** — search product, add to cart, complete cash payment, see receipt
+6. **Repair intake** — new intake form, step through all steps, create ticket
+7. **Repair queue** — filter by status, select ticket, see detail
+8. **Session attendance** — open lessons tab, select session, mark attended
+9. **Profile PIN setup** — navigate to profile, security tab, set PIN
+10. **Auto-lock** — verify station locks after timeout
+
+#### Setup
+```bash
+# Install
+bun add -d @playwright/test
+npx playwright install chromium
+
+# Config: packages/admin/playwright.config.ts
+# - baseURL: http://localhost:5173 (dev) or build + serve
+# - webServer: start backend + frontend before tests
+# - Use test DB with known seed data
+```
+
+#### Test structure
+```
+packages/admin/e2e/
+  fixtures/
+    auth.ts              -- login helper, PIN login helper
+    seed.ts              -- API calls to seed test data (accounts, products, tickets)
+  flows/
+    login.spec.ts
+    station-pos.spec.ts
+    station-repairs.spec.ts
+    station-lessons.spec.ts
+    profile.spec.ts
+    forgot-password.spec.ts
+```
+
+#### Auth fixtures
+```ts
+// Reusable login that stores auth state
+async function loginAsAdmin(page) {
+  await page.goto('/login')
+  await page.fill('[type=email]', 'admin@test.com')
+  await page.fill('[type=password]', 'TestPassword123!')
+  await page.click('button[type=submit]')
+  await page.waitForURL('**/accounts**')
+}
+
+async function pinLogin(page, employeeNumber, pin) {
+  await page.goto('/station')
+  // Type PIN digits
+  for (const digit of employeeNumber + pin) {
+    await page.click(`button:has-text("${digit}")`)
+  }
+  await page.waitForSelector('[data-slot="tabs"]')
+}
+```
+
+### Tier 2: Vitest + Testing Library (Component)
+**Priority: Medium — implement after E2E**
+
+Fast unit/integration tests for component logic, state management, and utility functions. Doesn't need a running backend (mocks API calls).
+
+- **Framework:** Vitest + `@testing-library/react`
+- **Runner:** `bun run test:unit` (in packages/admin)
+- **Location:** `packages/admin/__tests__/`
+
+#### What to test
+- **Zustand stores:** `pos.store.ts`, `station.store.ts` — state transitions, lock/unlock, activity tracking
+- **Form validation:** intake form step validation, PIN input, password requirements
+- **Permission routing:** repairs-station permission check (desk vs tech), lessons-station (desk vs instructor)
+- **Utility functions:** time formatting, status color mapping, receipt format toggle
+- **Component rendering:** key components render without crashing with mock data
+
+#### What NOT to test at component level
+- API integration (covered by E2E + API tests)
+- CSS/layout (covered by E2E visual checks)
+- Third-party component internals (shadcn, radix)
+
+### Tier 3: Visual Regression (Optional)
+**Priority: Low — nice to have**
+
+Screenshot comparison to catch unintended visual changes.
+
+- **Tool:** Playwright's built-in screenshot comparison (`expect(page).toHaveScreenshot()`)
+- **Scope:** Key pages only (login, station POS, repair intake, profile)
+- **Storage:** Baseline screenshots committed to repo
+
+## CI Integration
+
+```yaml
+# Add to .gitea/workflows/ci.yml
+
+  frontend-unit:
+    runs-on: ubuntu-latest
+    needs: ci
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -fsSL https://bun.sh/install | bash && echo "$HOME/.bun/bin" >> $GITHUB_PATH
+      - run: bun install --frozen-lockfile
+      - working-directory: packages/admin
+        run: bun run test:unit
+
+  frontend-e2e:
+    runs-on: ubuntu-latest
+    needs: ci
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -fsSL https://bun.sh/install | bash && echo "$HOME/.bun/bin" >> $GITHUB_PATH
+      - run: bun install --frozen-lockfile
+      - run: npx playwright install chromium --with-deps
+      # Start services (postgres, valkey)
+      # Run migrations + seed
+      # Start backend + frontend
+      # Run playwright tests
+```
+
+## Implementation Order
+
+1. **Set up Playwright** — config, install, first smoke test (login page loads)
+2. **Auth fixtures** — reusable login + PIN login helpers
+3. **Seed fixtures** — create test data via API (reuse API test patterns)
+4. **Login flow tests** — login, forgot password, redirect
+5. **Station flow tests** — PIN login, tab switching, POS sale
+6. **Repair flow tests** — intake form, queue, detail
+7. **Lesson flow tests** — attendance, schedule view
+8. **Set up Vitest** — config, first store test
+9. **Store tests** — POS store, station store
+10. **CI integration** — add to pipeline
+
+## Estimated Effort
+
+- Tier 1 (Playwright setup + 10 critical flows): ~1 session
+- Tier 2 (Vitest setup + store/component tests): ~1 session
+- CI integration: included in each tier