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