ui/docs/testing.md

@@ -9,7 +9,11 @@ this doc only covers the UI-specific tiers added in Phase 2 of
 
 Triggered by `.gitea/workflows/ui-test.yaml` on every push and pull
 request that touches `ui/**`, `backend/**`, `gateway/**`, `game/**`,
-`pkg/**`, `client/**`, `go.work`, or `go.work.sum`. Linux runner only.
+`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:
 
@@ -79,14 +83,92 @@ go test -count=1 \
   ./pkg/storage/... ./pkg/transcoder/... ./pkg/util/...
 ```
 
-## CI dry-run with `act`
+## Local CI verification
 
-Until the Gitea Actions runner is wired up, the workflow is exercised
+`tools/local-ci/` ships a self-contained Gitea + Actions runner via
-locally with [`act`](https://github.com/nektos/act):
+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`](../../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
 
 ```sh
-act -W .gitea/workflows/ui-test.yaml --container-architecture linux/amd64
+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
 ```
 
-`act` reads the workflow as GitHub Actions; the format is
+Default credentials baked in: `galaxy:galaxy-dev` (admin user, also
-intentionally compatible.
+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:
+
+```sh
+# 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:
+
+```sh
+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:
+
+```sh
+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.