galaxy-game/ui/docs/testing.md

UI Testing Tiers

UI client test toolchain. Project-wide testing layers (service / inter-service / system) live in ../../docs/TESTING.md; this doc only covers the UI-specific tiers added in Phase 2 of ../PLAN.md.

Tier 1 — per-PR

Triggered by .gitea/workflows/ui-test.yaml on every push and pull request that touches ui/**, backend/**, gateway/**, game/**, pkg/**, go.work, or go.work.sum. Linux runner only.

The actions/checkout@v4 step uses submodules: recursive, so the runner pulls every git submodule the suite depends on (today only pkg/geoip/test-data, the MaxMind-DB fixtures used by pkg/geoip).

Runs:

• go test over the monorepo Go modules, excluding two areas:

  • integration/ — needs Docker + testcontainers and is the project's make -C integration integration gate.
  • client/ — the deprecated Fyne client (see ../PLAN.md §74) is frozen; its tests are not run in CI.

  The pkg/<name>/ modules are listed one by one in the workflow because they are independent go.work modules and ./pkg/... does not recurse into separate modules. The exact command lives in .gitea/workflows/ui-test.yaml.

• pnpm test (Vitest + @testing-library/svelte + @testing-library/jest-dom) — component / unit tests under ui/frontend/tests/**/*.test.ts.

• pnpm exec playwright test — end-to-end smoke against pnpm run dev on port 5173. Four projects:

  • chromium-desktop (Desktop Chrome)
  • webkit-desktop (Desktop Safari)
  • chromium-mobile-iphone-13 (iPhone 13 viewport, Chromium engine)
  • chromium-mobile-pixel-5 (Pixel 5 viewport, Chromium engine)

Playwright traces and screenshots are retained on failure and uploaded as Gitea Actions artefacts (playwright-report and playwright-traces, 14-day retention).

Tier 2 — release

Triggered by .gitea/workflows/ui-release.yaml on tag push (v*). Currently mirrors the Tier 1 step set; the dedicated release-only checks land in later phases:

• Visual regression baseline check — Phase 33. Snapshots live in ui/frontend/tests/__snapshots__/ until the project shifts to Argos or another visual-diff service.
• iOS smoke (Capacitor + Appium) — Phase 32. Runs on a macos-13 runner once the Capacitor mobile wrapper exists.

Both blocks are present as commented sections in .gitea/workflows/ui-release.yaml with the phase number that re-enables them.

Local execution

From ui/frontend/:

pnpm test                                           # Vitest
pnpm exec playwright install                        # one-time
pnpm exec playwright test                           # all projects
pnpm exec playwright test --project=chromium-desktop
pnpm exec playwright show-report                    # open last HTML report

From the repository root, the same scope CI uses (backend serially because most packages spawn their own Postgres testcontainer and parallel bootstraps starve each other on constrained runners):

go test -count=1 -p 1 ./backend/...
go test -count=1 \
  ./gateway/... ./game/... \
  ./pkg/calc/... ./pkg/connector/... ./pkg/cronutil/... \
  ./pkg/error/... ./pkg/geoip/... ./pkg/model/... \
  ./pkg/postgres/... ./pkg/redisconn/... ./pkg/schema/... \
  ./pkg/storage/... ./pkg/transcoder/... ./pkg/util/...

Local development stack

For UI work that needs a real authenticated stack (verifying the FlatBuffers wire end-to-end, exercising a real lobby flow, hitting real Mailpit), bring up tools/local-dev/:

make -C tools/local-dev up        # postgres + redis + mailpit + backend + gateway
pnpm -C ui/frontend dev           # Vite on the host, talks to the stack

ui/frontend/.env.development already targets the stack (http://localhost:8080) and pins the matching response-signing public key from tools/local-dev/keys/. Per-developer overrides go into .env.development.local (gitignored).

The stack honours BACKEND_AUTH_DEV_FIXED_CODE (default 123456 in tools/local-dev/.env) so the login form takes that literal in addition to the real Mailpit code; see ../../tools/local-dev/README.md for the full runbook (regenerating the dev keypair, switching the mode off, troubleshooting common boot issues).

The local-dev stack is independent from the local-ci stack below; they bind different ports and can run side by side.

Synthetic reports for visual testing (DEV)

For visual checks of the map, inspectors and order-overlay against rich game states, the lobby exposes a DEV-only "Load synthetic report" affordance (import.meta.env.DEV). The flow is:

1. Convert a legacy text report (tools/local-dev/reports/{dg,gplus}/) to JSON with the Go CLI:

   go run ./tools/local-dev/legacy-report/cmd/legacy-report-to-json \
       --in  tools/local-dev/reports/dg/KNNTS039.REP \
       --out /tmp/dg39.json
   

   See ../../tools/local-dev/legacy-report/README.md for what the parser populates today and how to extend it when a new UI phase decodes a new Report field.

2. Run the UI dev server (pnpm -C ui/frontend dev), open the lobby, and use the "Load JSON…" file picker in the Synthetic test reports (DEV) section. The page navigates to /games/synthetic-<uuid>/map with the report wired into the in-game shell.

In synthetic mode:

• The map view, inspectors and races view render against the loaded report exactly as they would for a real game.
• Composing orders works locally (overlay applies through applyOrderOverlay as usual), but nothing is sent to the gateway — OrderDraftStore.scheduleSync short-circuits because the synthetic id is not a UUID and the layout deliberately does not bind a GalaxyClient for this game.
• The order draft is persisted into the platform Cache under the same order-drafts namespace as real games, keyed by the synthetic id, so navigating back into the same synthetic session restores the draft. The cache is cleared with __galaxyDebug.clearOrderDraft(gameId) (DEV debug surface).
• A page reload loses the in-memory report registry; opening the same synthetic id afterwards redirects to /lobby. Re-load the JSON to reseed.

The synthetic-report parity rule (see ../PLAN.md § Assumptions and Defaults) requires every UI phase that extends decodeReport to also extend the legacy parser in lockstep, or to record in the parser's README.md that the new field cannot be derived from legacy text. This keeps the synthetic-mode coverage in step with the contract as the UI grows.

Local CI verification

tools/local-ci/ ships a self-contained Gitea + Actions runner via docker-compose so workflow changes are exercised end-to-end on a real runner before pushing to a remote Gitea instance. On Apple Silicon the runner and every spawned workflow container are arm64-native (no QEMU). Full runbook lives in ../../tools/local-ci/README.md; the cheat sheet below covers the operations needed when working a phase that touches CI.

Bring up / push / tear down

make -C tools/local-ci up      # idempotent: gitea + runner + admin user + repo
make -C tools/local-ci push    # add `local-gitea` remote (first call) and push HEAD
make -C tools/local-ci status  # docker compose ps
make -C tools/local-ci logs    # tail container logs
make -C tools/local-ci down    # stop, keep state
make -C tools/local-ci clean   # stop and wipe volumes for a fresh start

Default credentials baked in: galaxy:galaxy-dev (admin user, also the owner of the galaxy/galaxy repo). Web UI on http://localhost:3000; runs at http://localhost:3000/galaxy/galaxy/actions.

Inspect a run from the shell

The Gitea Actions API is on http://localhost:3000/api/v1 with basic auth. Useful for verifying a workflow change without opening the browser:

# Latest workflow runs — `status` is a human-readable string here:
# "running" / "success" / "failure" / "cancelled".
curl -s -u galaxy:galaxy-dev \
  'http://localhost:3000/api/v1/repos/galaxy/galaxy/actions/tasks?limit=5' \
  | python3 -m json.tool

# Tight one-liner for the latest run only:
curl -s -u galaxy:galaxy-dev \
  'http://localhost:3000/api/v1/repos/galaxy/galaxy/actions/tasks?limit=1' \
  | python3 -c 'import json, sys; r=json.load(sys.stdin)["workflow_runs"][0]; print(r["run_number"], r["status"], r["display_title"])'

Step-by-step workflow output is stored zstd-compressed under /data/gitea/actions_log/galaxy/galaxy/<run_padded>/<job_index>.log.zst inside the gitea container:

docker compose -f tools/local-ci/docker-compose.yml exec -T gitea sh -c '
  apk add --quiet zstd
  zstdcat /data/gitea/actions_log/galaxy/galaxy/01/1.log.zst
' | less

<run_padded> is the run number, zero-padded to two digits (01, 02, …); <job_index> is the 1-based index of the job inside that run (only 1 for the current single-job workflows).

Typical phase workflow

When a phase changes anything under .gitea/workflows/ or surfaces new tests in CI:

1. Local sanity first — run the affected commands directly (pnpm test, pnpm exec playwright test, the targeted go test ./... slice).
2. Commit and make -C tools/local-ci push.
3. Poll the API for the latest run; once it leaves running, inspect status. On failure pull the log via the snippet above.
4. Fix and repeat. The runner is always-on; each push triggers a fresh run (test cache is cleared by -count=1 so a green run is honest).

Quick syntax-only dry-run with act

For a sub-second check that the workflow YAML is well-formed and action references resolve, without pulling images and without running anything:

act -W .gitea/workflows/ui-test.yaml -n push

act doesn't honour Gitea-specific behaviours (artifact storage, secrets, run triggers). Use it for syntax checks; fall back to the local Gitea above for honest end-to-end verification.