lunarfront-app/docs/frontend-testing-plan.md

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

# 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

// 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

# 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