diff --git a/docs/frontend-testing-plan.md b/docs/frontend-testing-plan.md new file mode 100644 index 0000000..7f5a423 --- /dev/null +++ b/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