# Frontend Test Coverage

## Purpose

Frontend tests protect the three-layer architecture by testing API/data-access and business logic directly, without rendering full product modules when rendering is not needed.

## Test Runner

- `npm run test` runs `vitest run`.
- `npm run test:e2e` runs backend-free Playwright smoke tests against a production build served by Vite preview.
- `npm run test:e2e:content` runs backend-seeded content catalog Playwright tests against a production build served by Vite preview.
- `npm run typecheck` remains the TypeScript gate.
- `npm run build` runs typecheck before Vite.

## Current Coverage

Current coverage includes architecture guardrails, API/data-access behavior, and pure business-layer behavior in these files:

- `frontend/src/app/appRoutes.test.ts`
- `frontend/src/business/app-shell/selectors.test.ts`
- `frontend/src/business/auth/hooks.test.tsx`
- `frontend/src/business/auth/mappers.test.ts`
- `frontend/src/business/auth/permissions.test.ts`
- `frontend/src/business/auth/selectors.test.ts`
- `frontend/src/business/campus-attendance/mappers.test.ts`
- `frontend/src/business/campus-attendance/printReport.test.ts`
- `frontend/src/business/campus-attendance/selectors.test.ts`
- `frontend/src/business/campuses/mappers.test.ts`
- `frontend/src/business/classroom-support/selectors.test.ts`
- `frontend/src/business/classroom-timer/selectors.test.ts`
- `frontend/src/business/communications/selectors.test.ts`
- `frontend/src/business/community/selectors.test.ts`
- `frontend/src/business/dashboard/selectors.test.ts`
- `frontend/src/business/director-dashboard/selectors.test.ts`
- `frontend/src/business/esa-funding/selectors.test.ts`
- `frontend/src/business/frame/mappers.test.ts`
- `frontend/src/business/frame/selectors.test.ts`
- `frontend/src/business/audio-files/selectors.test.ts`
- `frontend/src/business/audio-files/generate.test.ts`
- `frontend/src/business/personality/mappers.test.ts`
- `frontend/src/business/personality/selectors.test.ts`
- `frontend/src/business/policies/mappers.test.ts`
- `frontend/src/business/policies/selectors.test.ts`
- `frontend/src/business/safety-protocols/mappers.test.ts`
- `frontend/src/business/safety-protocols/selectors.test.ts`
- `frontend/src/business/safety-quiz/mappers.test.ts`
- `frontend/src/business/safety-quiz/selectors.test.ts`
- `frontend/src/business/sign-language/selectors.test.ts`
- `frontend/src/business/staff-attendance/mappers.test.ts`
- `frontend/src/business/staff-attendance/selectors.test.ts`
- `frontend/src/business/top-bar/selectors.test.ts`
- `frontend/src/business/user-progress/mappers.test.ts`
- `frontend/src/business/vocational/selectors.test.ts`
- `frontend/src/business/walkthrough/mappers.test.ts`
- `frontend/src/business/walkthrough/selectors.test.ts`
- `frontend/src/business/walkthrough/validators.test.ts`
- `frontend/src/business/zones/selectors.test.ts`
- `frontend/src/shared/api/auth.test.ts`
- `frontend/src/shared/api/campusAttendance.test.ts`
- `frontend/src/shared/api/campuses.test.ts`
- `frontend/src/shared/api/communications.test.ts`
- `frontend/src/shared/api/contentCatalog.test.ts`
- `frontend/src/shared/api/frame.test.ts`
- `frontend/src/shared/api/httpClient.test.ts`
- `frontend/src/shared/api/personality.test.ts`
- `frontend/src/shared/api/safetyQuizResults.test.ts`
- `frontend/src/shared/api/staffAttendance.test.ts`
- `frontend/src/shared/api/userProgress.test.ts`
- `frontend/src/shared/api/walkthrough.test.ts`
- `frontend/src/shared/architecture/import-boundaries.test.ts`
- `frontend/src/shared/business/apiListRows.test.ts`
- `frontend/src/shared/business/queryState.test.ts`
- `frontend/src/shared/constants/moduleRoutes.test.ts`
- `frontend/src/shared/errors/errorMessages.test.ts`
- `frontend/src/hooks/usePermissions.test.tsx`
- `frontend/src/components/sign-in-modal/SignInForm.test.tsx`

These tests verify import-boundary enforcement, centralized network access through `shared/api/httpClient`, alias-only source imports, required API contract-test coverage, HTTP client request normalization, cookie-backed auth refresh behavior, JSON body serialization, empty response handling, backend error propagation, API wrapper endpoint/query/body contracts, shared list/query/error helpers, route config, module route metadata, module access correction, sidebar navigation selectors, mobile sidebar overlay visibility, auth display/profile mapping, signup validation, campus mapping, dashboard and director dashboard selectors, classroom support selectors, timer formatting/progress/threshold parsing, DTO mapping, FRAME edit access, campus attendance mapping, calculations, and printable report output, staff attendance mapping and rollups, walkthrough create DTO mapping, walkthrough filtering, walkthrough check-in stats/history mapping, walkthrough scoring, generated summaries, repeated low-rating flags, communication role visibility, community catalog filtering and stats, ESA funding selectors, policy mapping/filtering/validation, safety-protocol mapping and authoring (steps/considerations) validation, audio-library management gating and the local recipe-generation stub, safety quiz compliance mapping and editable payload validation, sign language selectors, top bar display selectors, user progress normalization, vocational zip/category/search/stat calculations, zones selectors, personality DTO mapping, personality distribution grouping, EI thresholds, personality quiz progress, and MBTI-derived communication guidance.

The component and hook tests verify SignInForm rendering, loading states, user interactions, form submission, password visibility toggling, auth session initialization, sign-in/sign-out flows, AuthExpiredError handling, modal workflow state management, and permissions hook behavior including has(), hasAny(), hasAll() methods with globalAccess support.

The personality selector tests caught and now guard against a grouping defect where S/J and S/P types were classified from the third code character instead of the fourth code character.

The import-boundary tests enforce the three-layer dependency direction:

- API modules must not import business or view modules.
- Business modules must not import view modules.
- View modules must not call `frontend/src/shared/api/` directly.
- Source imports must use the configured `@` alias instead of relative paths.
- Direct `fetch` calls must stay centralized in `frontend/src/shared/api/httpClient.ts`.
- Runtime data access must stay centralized in the shared API layer.
- Every runtime module in `frontend/src/shared/api/` must have a colocated `.test.ts` contract test.

## Backend-Seeded E2E Coverage

Backend-seeded E2E tests live under:

- `frontend/tests/e2e/content-catalog.seeded.e2e.ts`
- `frontend/tests/e2e/accessibility.seeded.e2e.ts`
- `frontend/tests/e2e/rbac-access.seeded.e2e.ts`
- `frontend/tests/e2e/tenant-isolation.seeded.e2e.ts`
- `frontend/tests/e2e/provisioning.seeded.e2e.ts`
- `frontend/tests/e2e/product-workflow.seeded.e2e.ts`
- `frontend/tests/e2e/policy-acknowledgments.seeded.e2e.ts`
- `frontend/tests/e2e/audio-files.seeded.e2e.ts`

The seeded suite is intentionally excluded from default `npm run test:e2e` through `frontend/playwright.config.ts`. Run it with:

```bash
npm run test:e2e:content
```

Prerequisites:

- backend database migrations have run;
- backend database seeders have run;
- backend server is running at `VITE_BACKEND_API_URL`.

Test credentials are hardcoded (see `CLAUDE.md` for the full list):
- Admin: `admin@flatlogic.com` / `flatlogicAdmin123!`
- Users: `<role>@flatlogic.com` / `flatlogicUser123!`

The seeded suite verifies:
- Minimum content catalog seed set through the public backend API
- Classroom timer, classroom support, sign language, and zones routes with UI assertions based on live backend response
- RBAC access control for different user roles (teacher, director, superintendent access to appropriate routes)
- **Tenant isolation**: Users from one organization cannot read, list, update, or delete records from another organization
- **Scoped provisioning**: Creating an owner auto-creates and links a new company
- **Product workflows**: Director FRAME entries and staff progress tracking persist correctly
- **Policy acknowledgments**: document create/persist, manage-vs-read RBAC, per-version (idempotent) acknowledgment, and external-role lockout
- **Audio library**: `file`/`url`/`recipe` create/persist, same-campus read, kind/content validation, `support_staff` read-only, and external-role lockout

## Accessibility E2E Coverage

Accessibility tests use `@axe-core/playwright` to verify WCAG 2 AA compliance across all 19 application pages. Run them with:

```bash
npm run test:e2e:content -- --grep "accessibility"
```

The accessibility suite covers:

- Login page (unauthenticated)
- Dashboard
- Classroom Timer
- Classroom Support
- Sign Language
- Zones of Regulation
- F.R.A.M.E. Weekly
- Behavior Management
- Emotional Intelligence
- Attendance
- Parent Communication
- Internal Alerts
- Safety Protocols
- Handbook & Policies
- Community & Partnerships
- Vocational Opportunities
- ESA Funding Info
- Walk-Through Check-In
- Director Dashboard

Each test runs axe-core with WCAG 2 A and AA tags (`wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`) and fails on any violation. This ensures:

- Sufficient color contrast ratios (4.5:1 for normal text, 3:1 for large text)
- No nested interactive elements (buttons inside buttons)
- Proper ARIA labels and roles
- Keyboard accessibility
- Screen reader compatibility

## Rules For New Tests

- Prefer testing selectors, mappers, validators, and calculations before rendering full components.
- Cover shared API/client behavior with mocked `fetch`; do not call a live backend from unit tests.
- Keep import-boundary tests updated when adding a new top-level layer directory.
- Keep tests deterministic: no live backend, no network, and no current-time dependency unless the current date is injected.
- Use typed fixtures instead of `any` or unsafe casts.
- Add React/hook tests only when a workflow cannot be verified through pure functions.
- Use `renderHook` from `@testing-library/react` for hook tests; mock `useAuth` context when testing permission hooks.
- Use `render` from `@testing-library/react` and `userEvent` for component interaction tests.
- Keep backend-free Playwright smoke tests focused on high-value role/navigation workflows.
- Put live backend/database assertions only in explicit seeded suites such as `test:e2e:content`.