Test Architecture and Coverage Gaps

Audit date: 2026-03-23 Scope: Vitest unit/integration tests, Playwright E2E tests, test utilities, mock infrastructure

Historical audit: Do not use the file counts, route counts, or "zero tests" findings below as a current coverage map. Auth guards and the phase registry now have co-located tests, and the test corpus has grown substantially. For living conventions, see AHDGame's e2e/README.mdjust now and the co-located *.test.ts files.

Investigation Summary#

Audited a sample of the ~3123 test files across Vitest (unit/integration) and Playwright (E2E). The codebase has strong coverage of pure calculation functions (vote math, demographics, party org, formatting) but gaps remain in orchestration systems (turn processing, bill lifecycle, election resolution) and security-critical paths (auth, admin gates). The mock database utility enables fast tests but creates false confidence by not validating MongoDB queries or simulating real cursor behavior. Per-file test counts below are illustrative examples, not a full-repo audit.

1. Test Organization#

Structure#

Configuration#

• Vitest (vitest.config.ts2d ago): Node environment, globals, v8 coverage on src/lib/** only
• Playwright (playwright.config.ts10d ago): Chromium, parallel, 2 retries in CI, manual credentials

Helpers and Fixtures#

• src/lib/test-utils/mockDb.ts10d ago -- sole shared test utility; creates mock MongoDB Db with chainable cursors
• No shared test factories, fixtures, or builders
• No E2E seed scripts or fixture management

2. Test Classification by Purpose#

Strong Coverage (high-value, well-tested)#

Adequate Coverage (tests exist, reasonable depth)#

Weak Coverage (tests exist but shallow or misleading)#

Missing Coverage (no tests at all)#

See Section 3 below for the full ranked list.

3. Ranked Coverage Gaps by Risk and Value#

Tier 1: Critical -- Core Game Loop and Security#

Tier 2: High -- Major Subsystems#

Tier 3: Medium -- Supporting Systems#

Tier 4: Lower -- Utilities and Snapshots#

4. False-Confidence Tests#

These tests pass but provide misleading assurance:

4a. Mock Database Doesn't Validate Queries#

File: src/lib/test-utils/mockDb.ts10d ago

The mock creates stub collections where find(), findOne(), updateOne() etc. accept any arguments and return pre-configured values. This means:

• A broken MongoDB filter { stauts: "active" } (typo) passes all tests
• Incorrect $set operators in updateOne go undetected
• Aggregation pipelines are completely ignored -- aggregate() returns a stub toArray()
• ObjectId comparison is never validated (mock uses string IDs)

Impact: Any test using createMockDb() cannot detect broken queries. This affects ~80+ test files.

4b. Full Turn Flow "Integration" Test#

File: src/app/api/cron/turn/fullTurnFlow.integration.test.ts10d ago

Claims to test the full turn cycle but mocks every sub-processor and every database operation. The test passes if processTurn() calls the right functions in the right order -- but doesn't verify any phase produces correct output or that data flows between phases.

Specific false confidence: The test asserts gameState.updateOne was called, but doesn't check what was written. Turn could increment by 0, -1, or 999 and the test passes.

4c. Campaign Turn Test#

File: src/lib/turn/campaignTurn.test.ts10d ago

Single test asserts bulkWrite.toHaveBeenCalled() with no inspection of the bulk operations. Income calculation, action generation, maintenance costs, and endorsement effects are all unchecked.

4d. Election Resolution Tests#

File: src/lib/turn/electionResolution.test.ts10d ago

Tests spawnHouseElection parameters but never verifies the election document written has correct status, dates, or candidate configuration. Tests check insertOne was called, not what was inserted.

5. Brittle Tests#

5a. Next.js Header Mocking#

Multiple integration tests mock next/headers with:

vi.mock("next/headers", () => ({
  cookies: vi.fn().mockResolvedValue({ get: vi.fn(), set: vi.fn() }),
  headers: vi.fn().mockResolvedValue({ get: vi.fn() }),
}));

These break whenever Next.js changes the headers API (happened in Next.js 15 and 16). Each test file re-implements this mock slightly differently.

5b. Hard-coded Mock Return Values#

Tests like fullTurnFlow.integration.test.ts hard-code mock returns that mirror current implementation details:

• If a function signature changes (e.g., returns a different shape), mocks silently return stale data
• No type-safety between mock return values and actual function signatures

5c. E2E Tests with Flexible Text Matching#

E2E tests use patterns like:

expect(body).toMatch(/elections|no elections found|loading|to participate/i);

This passes for almost any page content and provides no meaningful assertion about the elections feature actually working.

6. E2E Coverage Assessment#

Current State: Smoke-Only#

Missing E2E Workflows#

Every interactive game feature is untested end-to-end:

1. User registration and character creation
2. Voting in elections
3. Bill creation and voting
4. Campaign launch and management
5. Party join/leave/management
6. Fund allocation
7. Admin operations
8. Cross-page data consistency (e.g., vote shows in election results)

Infrastructure Gaps#

• No E2E test fixtures or seed data
• No programmatic test account creation
• Manual .env.local credential setup
• No database state management between tests

7. Prioritized Coverage Expansion Plan#

Phase 1: Secure the Core (Weeks 1-2)#

Goal: Test the systems where bugs cause maximum damage.

Phase 2: Subsystem Integrity (Weeks 3-4)#

Phase 3: Mock Infrastructure Upgrade (Week 3, parallel)#

Phase 4: E2E Beyond Smoke (Weeks 5-6)#

8. Metrics (Current State)#

9. Remaining Risks and Deferred Issues#

Structural Risks#

1. No CI coverage gate -- coverage can regress silently. Consider adding a minimum threshold for src/lib/turn/ and src/lib/api/.
2. Integration tests require real DB -- the phase1/2/3 integration tests skip when MONGODB_URI is missing, which likely includes CI. These tests may never actually run.
3. No test for cross-collection consistency -- the system's biggest failure mode (partial writes across collections) has zero test coverage. Would require either transactions in tests or a dedicated consistency-check test.
4. E2E tests depend on external state -- no fixture management means E2E results are non-deterministic.

Deferred (Out of Scope for This Audit)#

• API route coverage expansion for all 409 routes (recommend risk-based selection)
• Component test coverage (low blast radius, skip per claude.md guidance)
• Performance regression tests beyond current load-time checks
• Chaos/fault-injection testing for turn processing resilience