# integration

End-to-end test suite for the Galaxy platform. The suite drives `gateway`
from outside and verifies behaviour at the public boundary while
`backend` and `galaxy/game` run as Docker containers managed by the
test process via `testcontainers-go`.

## Prerequisites

- A reachable Docker daemon (`DOCKER_HOST` or the local socket).
- Go toolchain matching the workspace `go.work` directive.
- Network access for the first run (`postgres:16-alpine`,
  `axllent/mailpit`, `redis:7-alpine` images are pulled). Subsequent
  runs reuse the local image cache.

## Run

```bash
go test ./integration/...
```

The suite builds three Docker images on demand from the workspace
sources:

- `galaxy/backend:integration` (`backend/Dockerfile`),
- `galaxy/gateway:integration` (`gateway/Dockerfile`),
- `galaxy/game:integration`     (`game/Dockerfile`).

Each image is built once per `go test` invocation, guarded by a
`sync.Once` inside `testenv`. The first cold run is slow (~2–3 min on
a developer machine); subsequent runs reuse the layer cache.

## Skipping

Tests skip with a clear message when the Docker daemon is unreachable.
Subsuites that require a live engine container (`lobby_flow_test.go`)
also skip when the `galaxy/game` image cannot be built.

## Layout

- `testenv/` — fixtures: Postgres, Redis, mailpit, GeoLite2 mmdb,
  image builders, backend/gateway runners, signed gRPC client (built
  on top of the public `galaxy/gateway/authn` package, no duplicated
  canonical-bytes code), mailpit HTTP client, `EnrollPilots` helper
  for runtime-driven scenarios that need ≥10 members, platform
  bootstrap.
- `*_test.go` — one file per cross-service scenario.

The runtime-driven tests (`runtime_lifecycle_test.go`,
`engine_command_proxy_test.go`) honour the engine's production
contract `len(races) >= 10`: each registers ten extra pilots with
synthetic `Player01..Player10` race names and matching emails, has
the owner invite each one, and has each pilot redeem the invite
before admin force-start. Cold runs add ~30 s for the ten extra
mailpit round-trips on top of the engine image build.

## Determinism

- Each test calls `Bootstrap(t)` to spin up a dedicated Postgres,
  Redis, mailpit, backend and gateway. Cross-test contamination is not
  possible.
- Tests do not call `t.Parallel()`. Docker resource pressure makes
  parallel suites flaky on commodity hardware.
- Gateway anti-abuse and body-size limits are loosened for the bulk of
  scenarios (so legitimate flows are not rate-limited mid-test) and
  intentionally tightened in `gateway_edge_test.go` so each protective
  mechanism can be observed firing.