knowfoolery/docs/4_work_plan/e2e_integration_tests_plan.md

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