40227-vm/frontend/docs/test-coverage.md

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/mappers.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/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-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/documents.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

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

Current Smoke Coverage

Playwright smoke tests live under:

• frontend/tests/e2e/app-shell.e2e.ts

The current smoke suite covers:

• teacher guest access to staff modules and absence of director-only modules;
• restricted executive route redirect for teacher guests;
• director guest access to director and walk-through navigation;
• superintendent guest access persistence after navigating between executive modules.

Backend-Seeded Content E2E Coverage

Backend-seeded content tests live under:

• frontend/tests/e2e/content-catalog.seeded.e2e.ts

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

VITE_BACKEND_API_URL=http://localhost:8080/api 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.

The seeded suite verifies the minimum content catalog seed set through the public backend API, then renders classroom timer, classroom support, sign language, and zones routes with UI assertions based on the live backend response.

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.
• 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.