# Scrabble Game — Testing

How the project is tested and the gate every stage must pass. Read before adding
tests or touching CI.

## Layers

- **Go unit tests** — table-driven where it helps; `testing` + standard library.
  Every functional change ships with regression coverage. Run:
  `go test -count=1 ./backend/... ./pkg/... ./gateway/...` (the module list grows
  with the workspace).
- **Integration** *(Stage 1+)* — Postgres-backed tests behind the `integration`
  build tag spin a throwaway `postgres:17-alpine` via `testcontainers-go`. They
  live in `backend/internal/inttest` and run with
  `go test -tags=integration -count=1 -p=1 ./backend/...` (needs Docker), guarded
  by a separate CI workflow (`integration.yaml`; Ryuk disabled, serial). Slow.
- **UI** *(introduced with the UI in Stage 7)* — Vitest (unit) + Playwright
  (e2e), mirroring the chosen plain-Svelte + Vite toolchain.
- **Engine** *(Stage 2+)* — correctness of scoring and move generation is owned
  by `scrabble-solver`'s own GCG-backed tests. `backend/internal/engine` adds, on
  top of the embedded solver: per-variant smoke tests (load all three committed
  DAWGs and validate a known word, including Эрудит), bag draw/return determinism
  and exchange accounting, the `Game` end-conditions (empty bag with an empty
  rack, and six scoreless turns) with end-game rack scoring, and
  **dictionary-independent history replay** (`ReplayBoard` reproduces a full
  greedy game's final board from decoded records alone), and the **resignation
  win/loss rule** (the resigner keeps their score yet loses). The engine tests
  read the DAWGs from `BACKEND_DICT_DIR` (or the sibling `scrabble-solver`
  checkout) and fail loudly when it is absent.
- **Game domain** *(Stage 3+)* — `backend/internal/game` adds pure unit tests
  (the GCG writer, the away-window / effective-deadline boundaries, the hint
  budget, the live-game cache and per-game lock, payload round-trips) plus
  Postgres-backed integration tests in `inttest` (full lifecycle to a natural
  end, **journal-replay equivalence**, the turn-timeout sweep with away-window
  grace, resign win/loss and statistics, the hint allowance-then-wallet policy,
  word-check and complaint capture, and per-game-lock serialisation). Stage 4 adds
  the engine's **multi-player drop-out** cases (continue after one resign,
  last-survivor win, the tile-disposition bag effect) and a domain integration test
  for a 3-player **timeout that continues**. The engine also gains a `Candidates`
  ranked/decoded test (Stage 5).
- **Social & lobby** *(Stage 4+)* — `backend/internal/social` unit-tests the chat
  **content filter** (links/emails/phones plus obfuscated forms) and
  `backend/internal/lobby` unit-tests the in-memory **matchmaker** (FIFO pairing,
  cancel, per-variant pools, plus the Stage 5 **robot substitution** reaper and
  `Poll` delivery) with fake game-creator and robot-provider seams. Postgres-backed
  `inttest` covers the friend request/accept lifecycle with the block/toggle guards,
  the per-user block (and its severing of friendships), chat post/list with the IP,
  content and block-visibility rules, the nudge turn/rate-limit rules, the
  invitation flow (all-accept starts the game, decline cancels, lazy expiry,
  inviter-only cancel), and the email confirm-code flow (request/confirm, taken
  email, expiry and attempt-cap) with a fixture mailer.
- **Robot** *(Stage 5+)* — `backend/internal/robot` unit-tests the pure strategy:
  the ≈ 40% play-to-win split over many seeds, the right-skewed move-delay
  (bounds, ~10-min median, determinism), the margin selection (win/lose, in-band
  and out-of-band fallbacks, no-play exchange/pass), the sleep window with drift
  and the midnight wrap, and mix restart-stability. Postgres-backed `inttest`
  drives a robot through a full auto-match to a natural end (asserting a robot
  statistics row), the matchmaker substitution end-to-end (enqueue → reap →
  `[human, robot]`, discoverable via `Poll`), and a proactive 12-hour nudge.
- **Gateway & contracts** *(Stage 6+)* — `backend/internal/notify` unit-tests the
  hub fan-out (delivery, overflow drop, unsubscribe) and the FlatBuffers event
  constructors (payload round-trip). `gateway/...` unit-tests are hermetic (no
  real network — an `httptest` fake backend and fixtures): the Telegram initData
  HMAC validator (genuine, tampered, wrong-token, stale), the session cache
  (hit/miss/fallback, TTL re-resolve, invalidate), the rate limiter (burst,
  per-key isolation, per-window), the push hub (per-user routing, overflow,
  unsubscribe), the transcode round-trips (FlatBuffers↔JSON, X-User-ID
  forwarding, nested GameView, domain-code surfacing), the admin Basic-Auth
  reverse proxy (401 / forward), and a full Connect `Execute` path end to end
  (guest auth, unauthenticated rejection, unknown message type). The backend gains
  the **guest** lifecycle (a guest plays an auto-match to a natural end yet accrues
  no statistics) and the **email-as-login** flow (request/verify, returning user)
  in `inttest`.

## Principles

- A green run must not depend on cached state: use `-count=1` in CI.
- Tests that need infrastructure fail loudly (`t.Fatal`) when it is unavailable
  rather than silently skipping coverage.
- No network or real platform calls in unit tests; validate platform
  credentials behind an interface seam and test with fixtures.

## Per-stage CI gate

Every completed stage is exercised on `gitea.iliadenisov.ru` before it is marked
done in [`../PLAN.md`](../PLAN.md):

1. Commit the stage on its `feature/*` branch.
2. Push to `origin`.
3. Watch the run to completion — never hand-roll a poll loop:
   `python3 ~/.claude/bin/gitea-ci-watch.py` (launch in the background).
4. Only after every workflow that fired is green may the stage be marked done.