# E2E Integration Tests Plan

## Objective
Implement end-to-end integration tests that validate real request paths from frontend test clients to gateway, backend services, and PostgreSQL/Redis persistence.

## Scope
- Validate real backend integration through gateway (`/api/v1`).
- Assert persistence side effects in service databases.
- Keep existing fast frontend-only Playwright tests unchanged.
- Add a dedicated full-stack Playwright suite and dedicated environment bootstrap.

## Success Criteria
- A dedicated command starts full-stack dependencies and runs integration E2E tests.
- At least 3 golden scenarios are covered with API + DB assertions.
- CI-ready artifacts and deterministic reset/seed flow are in place.
- Frontend lint/unit/E2E checks still pass.

## Phases

### Phase 1: Dedicated Full-Stack Environment
1. Create an E2E env file for compose with isolated ports.
2. Reuse production compose stack with auth disabled for test mode.
3. Add global setup/teardown scripts for Playwright to:
   - boot required services,
   - wait for health readiness,
   - reset DB state before suites.

### Phase 2: Data Reset + DB Assertion Tooling
1. Add helper utilities to execute SQL assertions against Postgres in Docker.
2. Add deterministic DB reset/truncate helpers across service databases.
3. Add optional seed helpers for initial baseline data.

### Phase 3: Full-Stack Test Scenarios
1. Leaderboard persistence and UI rendering:
   - POST update through gateway,
   - assert row in `leaderboards.leaderboard_entries`,
   - verify frontend leaderboard page renders persisted player.
2. Admin question CRUD persistence:
   - create/update/delete question through gateway admin endpoints,
   - assert `questions.questions` row state after each operation.
3. Gateway + service health and contract checks:
   - verify integration health endpoints and stable response envelopes.

### Phase 4: Commands and CI Integration
1. Add dedicated Playwright config for full-stack suite.
2. Add `frontend` script to run full-stack E2E.
3. Add `make` command wrapper for full-stack E2E.
4. Keep this suite separate from fast frontend-only E2E.

### Phase 5: Stabilization
1. Use deterministic IDs and explicit cleanup.
2. Force serial execution for integration suite to avoid DB race conditions.
3. Collect actionable failure outputs (HTTP body + SQL counts) in assertions.

## Deliverables
- `infrastructure/e2e/.env.e2e`
- `frontend/apps/web/playwright.fullstack.config.ts`
- `frontend/apps/web/e2e/full-stack/*` tests + helpers + setup/teardown
- `frontend/package.json` script additions
- `Makefile` target additions