Testing (E2E & Unit)
Relevant source files
The following files were used as context for generating this wiki page:
The testing architecture of the Lou Gehrig Fan Club (LGFC) project is designed to enforce strict design invariants and functional reliability. It utilizes a multi-layered approach consisting of unit tests for logic, component tests for structural integrity, end-to-end (E2E) tests for user workflows, and specialized audit scripts to prevent "design drift."
The testing suite ensures that the website adheres to the "V6 Specification," a set of design and structural requirements for the homepage and core components. This includes verifying specific CSS tokens, section ordering, and exact copywriting.
Sources: tests/homepage-structure.test.tsx:10-20, package.json:49-65, audits/verify_v6_lock.sh:10-15
Testing Frameworks and Tooling
The project utilizes several industry-standard tools to manage different testing tiers. These are integrated into the package.json scripts for developer convenience and CI/CD automation.
| Tool | Purpose | Primary Commands |
|---|---|---|
| Vitest | Unit and Component Testing | npm run test, npm run test:watch |
| Playwright | End-to-End (E2E) Testing | npm run test:e2e, npm run test:e2e:ui |
| Testing Library | React Component DOM testing | Used within Vitest suites |
| Bash/Grep | Design Audit and Lock Verification | sh audits/verify_v6_lock.sh |
Sources: package.json:49-63
Unit and Component Testing (Vitest)
Unit tests focus on isolated logic, such as data moderation helpers and API response parsing, while component tests (using @testing-library/react) verify that UI components render correctly and handle user interactions.
Homepage Structure Guard
A critical component test, the "Homepage Structure Drift Guard," enforces the order and presence of specific sections to ensure compliance with the V6 specification.
The diagram above illustrates the strictly enforced rendering order of homepage sections.
Sources: tests/homepage-structure.test.tsx:102-138
FAQ Page Testing
The FAQ page tests verify complex client-side behaviors, including:
- Loading & Filtering: Fetching approved entries via
apiGetand filtering by search query. - Ordering: Ensuring pinned entries appear first, followed by unpinned entries sorted by
updated_atdescending. - Analytics: Optimistic UI updates for view counts and subsequent
apiPostcalls to the view tracking endpoint. - Resiliency: Handling API failures and clearing timeout errors if a delayed fetch eventually succeeds.
Sources: tests/faq-page.test.tsx:45-165
Logic and Moderation Helpers
Tests in tests/faq-moderation.test.ts validate internal functions used for state management and administrative authorization.
- Parsing: Strict boolean, positive integer, and pinned status parsing.
- Validation: Ensuring FAQ questions and answers meet length and presence requirements.
- Auth: "Fail-closed" logic for admin token verification.
Sources: tests/faq-moderation.test.ts:16-72
End-to-End Testing (Playwright)
E2E tests verify that the application works as expected from the user's perspective by running in actual browser environments.
V6 Token Compliance
Specific tests are dedicated to verifying "Design Tokens." These tests evaluate the computed styles of elements to ensure they match approved specifications.
- Color Verification: Ensuring
h2.title-lgfcand.joinBanneruse the exact RGB valuergb(0, 51, 204). - Spacing: Verifying the
.topWhitespacespacer exists and maintains a height of exactly72px. - Content: Asserting exact string matches for critical marketing copy (e.g., the Join Banner text).
Sources: tests/homepage.spec.ts:10-53
Section Visibility and Content
Regression tests ensure that major homepage sections (e.g., Weekly Matchup, Social Wall, Milestones) are not only present in the DOM but are visible to users and contain non-empty content.
The sequence above shows the verification flow for structural and visibility checks during E2E testing.
Sources: tests/e2e/homepage-sections.spec.ts:21-95
Design Lock Audits
Beyond standard test runners, the project includes specialized audit scripts (audits/verify_v6_lock.sh) that act as a "governance check." These scripts use shell commands to verify:
- Anchor Documents: Presence of critical governance files (e.g.,
website-PR-process.md). - CSS Invariants: Grepping
globals.cssfor mandatory class definitions like.section-gapand.title-lgfc. - Component Structure: Checking for the presence of specific class names and the absence of forbidden styles (e.g., ensuring the Header is not
sticky).
Sources: audits/verify_v6_lock.sh:16-75
Summary
The Lou Gehrig Fan Club project employs a robust testing suite that prioritizes design consistency and functional reliability. By combining Vitest for structural guarding and logic validation, Playwright for E2E user flows and style verification, and custom audit scripts for repo governance, the project maintains a "lock" on its V6 design specification while ensuring a bug-free experience for users.