admin/40227-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
40227-vm/frontend/docs/test-coverage.md
Dmitri caa7cf0d0f roles and permissions implementation
2026-06-12 06:55:35 +02:00

10 KiB
Raw Blame History

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:

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:

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.