# 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** — 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** — Vitest (unit) + Playwright (e2e), mirroring the chosen plain-Svelte + Vite toolchain. Vitest covers the FlatBuffers codecs (friend list, invitation, stats), the win-rate derivation and the GCG share/download choice, plus Playwright specs against the mock for the friends screen (code issue/redeem, accept a request), the lobby invitations section, the stats screen, profile editing, and the GCG export's finished-only visibility. - **Engine** — 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** — `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). It also covers 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**, and the engine's `Candidates` ranked/decoded test. - **Social & lobby** — `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 **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. It also covers the **befriend-an-opponent** gate (a request needs a shared game), the **permanent decline** and 30-day re-send rule, the **one-time friend code** (issue/redeem, self/single-use, decline-bypass), `ListInvitations`, the zero-value `GetStats`, and the GCG **finished-only** gate. - **Robot** — `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** — `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 edge-hardening cases: an oversized `Execute` payload is refused (`resource_exhausted`, the `GATEWAY_MAX_BODY_BYTES` cap), a limiter rejection lands in `gateway_rate_limited_total{class}` and the rejection tracker (drain/aggregate unit tests), the report POST reaches `/api/v1/internal/ratelimit/report` with the agreed JSON shape, the `/_gm` mount is 429-guarded by the per-IP admin class, and the gateway's `/` 308-redirects to `/app/` (the landing left the embed). The backend covers 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`. Gateway transcode round-trips cover the social/account operations (friends list, friend code issue/redeem, invitation create, stats, GCG, the profile-update away round-trip) and a `notify`-event constructor round-trip. - **Admin & dictionary ops** — `backend/internal/adminconsole` unit-tests the template renderer over every page plus the embedded asset; `backend/internal/engine` adds the **dictionary hot-reload** cases (`LoadAvailable` loads only the present variants, `OpenWithVersions` scans version subdirectories, a reload registers a new version and moves "latest"); `backend/internal/server` unit-tests the console's **same-origin** CSRF guard; the gateway adds the **verbatim `/_gm` Basic-Auth proxy** (401 / forward, path preserved) and the h2c **console mount** (routed when configured, 404 when not). Postgres-backed `inttest` drives the **complaint resolution → dictionary-change pipeline** (file → resolve with a disposition → pending change → mark applied), the admin **list/count** read queries, and the **/_gm console over HTTP** (pages render; a resolve POST needs a same-origin header). `ratewatch` has unit tests (window accumulation, the auto-flag threshold + expiry, the bounded episode map), the account-store **high-rate flag round-trip** (set-once / clear / re-flag) and a console flow in `inttest`: a gateway report auto-flags the account, the **Throttled** page shows the episode and the flagged queue, the user card carries the marker and the CSRF-guarded **Clear** reverses it. - **Observability & performance** — `pkg/telemetry` unit-tests the exporter selection (`none`/`stdout`/`otlp` build providers; OTLP constructs with no collector; the nil-runtime fallback). The domain metrics are exercised through a manual `sdkmetric` reader: `backend/internal/game` and `…/social` assert the counters and histograms record with the right `variant`/`kind` attributes, and `gateway/internal/connectsrv` asserts `edge_request_duration` by `message_type`/ `result`. Config tests cover the new telemetry env vars (backend/gateway/connector — `otlp` now accepted, an unsupported exporter rejected) and the guest-reaper knobs. Postgres-backed `inttest` drives the **guest reaper** end to end (an abandoned guest is reaped; a too-young guest, a seated guest and a durable account are kept). - **Load test & resource baseline** — a reusable `loadtest/` module (`scrabble/loadtest`) is the pre-release stress harness. It **seeds** a large account population with pre-created sessions directly in Postgres (token hashes matching `backend/internal/session`), **drives** virtual players through the edge protocol — real games assembled via invitations, **mid-ranked** legal moves generated locally by the embedded `scrabble-solver` (the edge carries no board, so the client replays history) — plus a fraction of nudge/chat/check-word/draft/profile/stats ops, and a **gateway-hammer** that verifies the rate limiter. Its own Go unit tests cover the pure pieces (token hashing, board replay vs. `board.Parse`, rack reconstruction, mid-rank selection, the report); the DAWG-backed move test runs under `BACKEND_DICT_DIR` (as the engine tests do). It is **not** part of the per-PR suite's behavioural assertions: it runs ad hoc as a one-shot container against the contour, producing a trip report (bugs + a resource baseline) read off the **cAdvisor + postgres_exporter** Grafana dashboard on the contour. See [`../loadtest/README.md`](../loadtest/README.md). ## 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.