Ilia Denisov
dcd8de8b00
- pkg/telemetry: shared OTel provider bootstrap (none/stdout/otlp + W3C
propagators + Go runtime metrics); backend/internal/telemetry becomes a thin
facade keeping its gin middleware.
- Telemetry parity: gateway and the Telegram connector gain telemetry runtimes
and config (GATEWAY_/TELEGRAM_ SERVICE_NAME + OTEL_*); otelgrpc instruments the
backend push server, the gateway's backend+connector clients and the connector
server. Default exporter stays none (collector/dashboards are Stage 14).
- Operational metrics (variant attribute on game-scoped ones): game_replay_duration,
game_move_validate_duration, games_started_total, games_abandoned_total,
game_cache_active, chat_messages_total{kind}, gateway edge_request_duration.
Wired via the SetMetrics setter pattern (default no-op meter).
- TODO-3: account.GuestReaper deletes guests with no game seat past
BACKEND_GUEST_RETENTION (default 30d, swept every BACKEND_GUEST_REAP_INTERVAL).
- Tests: pkg/telemetry exporter selection; game/social/edge metric recording via
a manual reader; config (otlp accepted, guest knobs); inttest guest reaper.
- Docs: PLAN.md re-scopes Stage 12 and adds Stage 13 (alphabet-on-wire) + Stage 14
(CI/deploy) with the agreed dictionary-versioning resolution; ARCHITECTURE 11/13,
TESTING, the three READMEs and FUNCTIONAL(+ru) updated.
125 lines
8.3 KiB
Markdown
125 lines
8.3 KiB
Markdown
# 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. Stage 8 adds Vitest for
|
|
the new 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** *(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. Stage 8 adds 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** *(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`. Stage 8 adds gateway transcode round-trips for the new 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** *(Stage 10)* — `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).
|
|
- **Observability & performance** *(Stage 12)* — `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).
|
|
|
|
## 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.
|