docs: reorder & testing

integration/scripts/preclean.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Pre-run cleanup for galaxy/integration. Idempotent and safe to call
+# repeatedly; runs before each integration test session to wipe state
+# left over from earlier runs.
+#
+# What we touch:
+#   1. Containers labelled `org.testcontainers=true` — every container
+#      brought up by testcontainers-go (our backend/gateway/game plus
+#      postgres/redis/mailpit/ryuk service containers).
+#   2. Containers labelled `galaxy.backend=1` — engine instances spawned
+#      by backend's runtime adapter on the host Docker daemon (see
+#      `backend/internal/dockerclient/types.go`). These do not carry
+#      the testcontainers label because backend, not testcontainers,
+#      creates them.
+#   3. Networks labelled `org.testcontainers=true` — networks created
+#      by testcontainers-go for cross-container wiring.
+#   4. Images labelled `galaxy.test.kind=integration-image` — local
+#      builds of galaxy/{backend,gateway,game}:integration. Pulled
+#      service images (postgres, redis, ryuk, mailpit) are NOT touched
+#      so the cache stays warm between runs.
+#
+# What we never touch:
+#   - Containers / images without one of the labels above.
+#   - User-managed images and volumes.
+
+set -euo pipefail
+
+remove_containers_with_label() {
+    local label="$1"
+    local description="$2"
+    local ids
+    ids=$(docker ps -aq --filter "label=$label" 2>/dev/null || true)
+    if [ -z "$ids" ]; then
+        return
+    fi
+    local count
+    count=$(printf '%s\n' "$ids" | wc -l | tr -d ' ')
+    echo "preclean: removing $count $description"
+    # shellcheck disable=SC2086
+    docker rm -f $ids >/dev/null 2>&1 || true
+}
+
+remove_networks_with_label() {
+    local label="$1"
+    local description="$2"
+    local ids
+    ids=$(docker network ls -q --filter "label=$label" 2>/dev/null || true)
+    if [ -z "$ids" ]; then
+        return
+    fi
+    local count
+    count=$(printf '%s\n' "$ids" | wc -l | tr -d ' ')
+    echo "preclean: removing $count $description"
+    # shellcheck disable=SC2086
+    docker network rm $ids >/dev/null 2>&1 || true
+}
+
+remove_images_with_label() {
+    local label="$1"
+    local description="$2"
+    local ids
+    ids=$(docker images -q --filter "label=$label" 2>/dev/null || true)
+    if [ -z "$ids" ]; then
+        return
+    fi
+    local count
+    count=$(printf '%s\n' "$ids" | sort -u | wc -l | tr -d ' ')
+    echo "preclean: removing $count $description"
+    # shellcheck disable=SC2086
+    docker rmi -f $ids >/dev/null 2>&1 || true
+}
+
+if ! command -v docker >/dev/null 2>&1; then
+    echo "preclean: docker CLI not found, nothing to do" >&2
+    exit 0
+fi
+
+if ! docker info >/dev/null 2>&1; then
+    echo "preclean: docker daemon unreachable, nothing to do" >&2
+    exit 0
+fi
+
+remove_containers_with_label "org.testcontainers=true" "testcontainers-managed containers"
+remove_containers_with_label "galaxy.backend=1"       "backend-managed engine containers"
+remove_networks_with_label   "org.testcontainers=true" "testcontainers-managed networks"
+remove_images_with_label     "galaxy.test.kind=integration-image" "integration-built images"
+
+echo "preclean: done"

integration/scripts/runstep.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Sequential one-test-at-a-time integration run.
+#
+# Runs every Test* function under `galaxy/integration` in a fresh
+# Docker state — preclean + single-test `go test -run` invocation —
+# stopping on the first failure. Use this to:
+#
+#   - Diagnose which test brings the suite down on a slow or
+#     overloaded Docker.
+#   - Build confidence on a host that cannot run the full suite in
+#     one shot.
+#
+# Slower than `make integration` (every test pays the bootstrap cost
+# of its own backend/gateway/postgres) but each iteration is
+# self-contained, so a flaky test cannot silently poison its
+# successors.
+#
+# Environment:
+#   STEP_TIMEOUT     per-test timeout (default 5m).
+#   STEP_PRECLEAN    set to 0 to skip the preclean step before each
+#                    test. Default is 1; only disable on a hand-cleaned
+#                    Docker that you are sure has no leftover state.
+#   STEP_VERBOSE     set to 0 to suppress `-v`. Default 1.
+#
+# Ryuk: this runner exports TESTCONTAINERS_RYUK_DISABLED=true. Ryuk
+# does not start cleanly on the local colima setup; the per-step
+# preclean handles leftover state by label. Override by setting
+# TESTCONTAINERS_RYUK_DISABLED=false in the calling shell.
+
+set -euo pipefail
+export TESTCONTAINERS_RYUK_DISABLED="${TESTCONTAINERS_RYUK_DISABLED:-true}"
+
+cd "$(dirname "$0")/.."
+
+readonly STEP_TIMEOUT="${STEP_TIMEOUT:-5m}"
+readonly STEP_PRECLEAN="${STEP_PRECLEAN:-1}"
+readonly STEP_VERBOSE="${STEP_VERBOSE:-1}"
+
+go_test_flags=(-count=1 -timeout="$STEP_TIMEOUT" -p=1 -parallel=1)
+if [ "$STEP_VERBOSE" = "1" ]; then
+    go_test_flags+=(-v)
+fi
+
+# Discover every top-level Test in the integration module. `go test
+# -list` honours build tags and filters; `^Test` picks up the standard
+# Go test convention.
+mapfile -t tests < <(go test -list '^Test' ./... 2>/dev/null | grep -E '^Test' | sort -u)
+if [ "${#tests[@]}" -eq 0 ]; then
+    echo "runstep: no tests found under ./..." >&2
+    exit 1
+fi
+
+echo "runstep: discovered ${#tests[@]} tests; per-test timeout $STEP_TIMEOUT"
+
+passed=0
+failed=""
+for name in "${tests[@]}"; do
+    if [ "$STEP_PRECLEAN" = "1" ]; then
+        bash scripts/preclean.sh
+    fi
+    echo
+    echo "============================================================"
+    echo "runstep: $name"
+    echo "============================================================"
+    if go test "${go_test_flags[@]}" -run "^${name}$" ./...; then
+        passed=$((passed + 1))
+        continue
+    fi
+    failed="$name"
+    break
+done
+
+if [ -n "$failed" ]; then
+    echo
+    echo "runstep: FAILED at $failed (after $passed passes)"
+    echo "         drill down with: go test -run '^${failed}$' -v ./..."
+    exit 1
+fi
+
+echo
+echo "runstep: all ${#tests[@]} tests passed"