knowfoolery/docs/4_work_plan/fullstack-e2e-integration-tests.md

Full-Stack E2E Integration Tests Plan

Goal

Ensure full-stack end-to-end integration tests cover at least the same scenarios as frontend-only E2E tests, while adding backend and database assertions where feasible.

Strategy

1. Build a source-to-fullstack scenario parity matrix.
2. Implement full-stack tests that mirror source scenario names.
3. Add typed DB helpers for deterministic assertions.
4. Add a parity gate script that fails if full-stack coverage drops below source coverage.
5. Wire parity and full-stack execution into standard local commands.

Coverage Matrix

Source E2E Scenario	Full-Stack Equivalent
player registration and demo login flow	player registration and demo login flow
complete game session flow	complete game session flow
leaderboard viewing flow	leaderboard viewing flow
admin question management flow	admin question management flow
profile route requires auth, then allows access after demo login	profile route requires auth, then allows access after demo login
start new game from home and render first playable question	start new game from home and render first playable question
hint usage reduces awarded score for a correct answer	hint usage reduces awarded score for a correct answer
after 3 wrong answers, game advances to next question	after 3 wrong answers, game advances to next question
session timeout ends game and redirects to results	session timeout ends game and redirects to results
results remain visible after page reload	results remain visible after page reload
leaderboard shows empty and error states from API	leaderboard shows empty and error states from API
admin can create, edit, then delete a question	admin can create, edit, then delete a question
admin form validation blocks invalid submission	admin form validation blocks invalid submission
mobile player flow keeps core controls visible	mobile player flow keeps core controls visible

Implementation Phases

Phase 1: Parity Suite

• Add a dedicated full-stack parity spec mirroring all source E2E scenario names.
• Keep tests serial and deterministic.

Phase 2: DB and API Assertion Helpers

• Extend full-stack helpers with typed assertion/query utilities.
• Add scenario-specific reset/seed calls before each test.

Phase 3: Parity Gate

• Add a script that parses source and full-stack test names.
• Fail if any source test name has no full-stack counterpart.

Phase 4: Command Wiring

• Add package script for parity check.
• Keep test:e2e:fullstack as execution command for the integration suite.

Exit Criteria

• All source E2E scenarios have matching full-stack scenario names.
• Full-stack suite passes.
• Parity check passes and can be run locally/CI.