Milestone 1.0.1: Go Integration Test Infrastructure

Status: Complete
Goal: 1.0 Test infrastructure (prerequisite)
Phase: 1 — Core Platform

Summary

Introduce a shared Go integration test harness: //go:build integration tagging (already adopted), internal/testutil helpers, local testcontainers option, and make test-integration. CI continues to use GitHub Actions service Postgres (no testcontainers in required checks).

Branch

chore/m1-0-1-integration-test-infra

PR title

chore(test): Go integration test infrastructure (m1.0.1)

Estimated effort

2–3 days

Prerequisites

Foundation-004 and milestones 1.1.1–1.1.3 merged on main
make compose-test-up or Docker available for testcontainers mode

Tasks

Add infra/testing/testutil (SetupPostgres, OpenDB, RLS helpers, fixtures)
Document testcontainers-go admission in DEPENDENCIES.md (optional submodule follow-up; compose path in root module)
Add make test-integration / dev-tool.sh test-integration
Refactor services/auth/validate_integration_test.go to use testutil.SetupPostgres
Package smoke test: go test -tags=integration ./infra/testing/testutil/...
Document dual local modes in DEVELOPMENT_GUIDE.md and ENVIRONMENT_VARIABLES.md
Record decision: CI service containers vs local testcontainers in decisions.md
Contributor execution materials prepared

Integration surfaces (existing CI)

Surface	Job / command	Postgres source
Migrations	`db-migrate-smoke`	GHA service container
Proto contracts	`proto-contract`	N/A (buf + stubs)
Auth validation	`auth-validate-smoke`	GHA service + `POSTGRES_TEST_DSN`

This milestone does not add a new required CI job.

Local modes

Compose test stack (default) — make compose-test-up, port 5433, POSTGRES_TEST_DSN optional override.
Testcontainers — IBEX_USE_TESTCONTAINERS=1 starts pgvector/pgvector:pg16 and runs migrations automatically.

Files affected

Path	Action
`infra/testing/testutil/*.go`	Add (integration build tag; testcontainers optional tag)
`go.mod` / `go.sum`	No testcontainers yet (compose-only); optional submodule follow-up
`Makefile` / `infra/scripts/dev-tool.sh`	`test-integration` target
`services/auth/validate_integration_test.go`	Refactor to testutil
`docs/DEVELOPMENT_GUIDE.md`	Integration test section
`docs/DEPENDENCIES.md`	testcontainers admission
`docs/ENVIRONMENT_VARIABLES.md`	`IBEX_USE_TESTCONTAINERS`
`phase-1-core-platform/decisions.md`	CI vs local containers
contributor workspace	Add

Testing requirements

go test ./... (unit, no integration tag) passes
make compose-test-up then go test -tags=integration ./services/auth/... passes
IBEX_USE_TESTCONTAINERS=1 go test -tags=integration ./internal/testutil/... passes when Docker is available
Required CI unchanged and green

Definition of done

make test-integration runs all integration-tagged tests with documented env
testutil.SetupPostgres works in compose and testcontainers modes
RLS smoke test proves org-scoped visibility in infra/testing/testutil
Auth integration tests use testutil without duplicating DSN/migrate boilerplate
DEVELOPMENT_GUIDE.md and execution prompt published

Risks

Risk	Mitigation
testcontainers slow or flaky on some hosts	Compose test stack remains default; testcontainers opt-in
`internal/` import rules	testutil lives under `infra/testing/`; uses SQL fixtures, not `services/auth/internal`
Docker-in-Docker in CI	Do not require testcontainers in merge gates