test: share testcontainers per service via pkg/testutil

CLAUDE.md

@@ -149,10 +149,34 @@ All commands are wrapped in the root Makefile. Always use `make` targets — nev
 - Every exported function in `pkg/` must have corresponding test cases
 
 ### Integration Tests
-- All integration tests use `//go:build integration` build tag
-- Use `testcontainers-go` with official modules (`mongodb`, `cassandra`, `nats`) for real dependencies
-- Write `setup<Dep>(t *testing.T)` helpers that start a container, register `t.Cleanup`, and return a connected client
-- Use `<service>_test` as database name to avoid collisions
+- All integration tests use the `//go:build integration` build tag
+- Test files live in the same package as the code under test (`package main` for services, `package <pkg>` for libraries) — never external `*_test` packages
+- **Containers come from `pkg/testutil`** — do not start your own with `testcontainers.GenericContainer` / `natsmod.Run` / `mongodb.Run` etc. Process-shared helpers (one container, many tests, started via `sync.Once`, terminated via `TerminateAll`):
+  - `testutil.MongoDB(t, prefix) *mongo.Database` — isolated DB per test
+  - `testutil.CassandraKeyspace(t, prefix) (keyspace, *gocql.Session, host)` — isolated keyspace per test
+  - `testutil.MinIO(t, prefix) (*minio.Client, bucket)` — isolated bucket per test
+  - `testutil.Elasticsearch(t) string` — shared ES URL; pair with `testutil.ElasticsearchIndex(t, prefix)` for a per-test isolated index (DELETEd on cleanup)
+  - `testutil.NATS(t) string` — shared NATS URL with JetStream enabled
+- Valkey (cluster-mode — services use this in production):
+  - `testutil.SharedValkeyCluster(t) *redis.ClusterClient` — process-shared cluster (started via `sync.Once`, reaped via `TerminateValkey`/`TerminateAll`). Per-test caller MUST register `t.Cleanup(func() { testutil.FlushValkey(t) })` so sibling tests start with a clean keyspace. Default choice.
+  - `testutil.StartValkeyCluster(t) *redis.ClusterClient` — per-test cluster (each test gets its own container via `t.Cleanup`). Use ONLY when the test asserts on cluster-routing state (e.g., `pkg/roomkeystore`'s `CLUSTER KEYSLOT` checks) or owns a store wrapper that calls `Close()` on the underlying client.
+- **Every integration test package must have a `TestMain` that drives cleanup**:
+  ```go
+  //go:build integration
+  package mypkg
+
+  import (
+      "testing"
+      "github.com/hmchangw/chat/pkg/testutil"
+  )
+
+  func TestMain(m *testing.M) { testutil.RunTests(m) }
+  ```
+  `testutil.RunTests` wraps `m.Run()` + `testutil.TerminateAll()` + `os.Exit(code)`. For concurrent pre-warming use `testutil.RunTestsWithPrewarm(m, testutil.EnsureElasticsearch, testutil.EnsureNATS, ...)` — runs each `EnsureXxx` concurrently and fails fast on the first error before `m.Run`. The `testutil.PrewarmFailFast(fns...)` building block is also exposed for packages that need extra cleanup between `m.Run` and `os.Exit`.
+- **Ryuk is disabled repo-wide** (via `pkg/testutil/init.go`) because our CI runner can't run the reaper sidecar. `testutil.TerminateAll` is the only cleanup mechanism on clean exits. SIGKILL / Ctrl+C will leak containers locally — acceptable trade-off; flip Ryuk back on with `TESTCONTAINERS_RYUK_DISABLED=false go test ...` if debugging a leak.
+- Per-test isolation is the caller's responsibility: the `MongoDB`/`Cassandra`/`MinIO` helpers already hash `t.Name()`; for ES use a per-test unique index name and DELETE on cleanup; for NATS use a per-test `*nats.Conn` pair with `Drain`/`Shutdown` cleanups; for shared Valkey call `testutil.FlushValkey(t)` in `t.Cleanup` (StartValkeyCluster's per-test mode is automatic).
+- Inline `testcontainers.GenericContainer` is only acceptable when a shared testutil container can't accommodate the test (e.g. search-service CCS needs two ES nodes on a shared docker network; `pkg/roomkeysender` needs NATS with WebSocket transport; `pkg/roomcrypto` needs a Node container with bundled scripts). Each inline container must store its reference and register `t.Cleanup(container.Terminate)`.
+- New shared dependencies (a container type used by ≥2 packages) belong in `pkg/testutil` with the same shape: `Xxx(t)` + `EnsureXxx()` + `TerminateXxx()`, container ref stored at package level, and `TerminateXxx` wired into `TerminateAll`.
 
 ### Model Tests
 - `pkg/model/model_test.go` verifies all domain types marshal/unmarshal correctly via a generic `roundTrip` helper

broadcast-worker/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package main
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

history-service/internal/cassrepo/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package cassrepo
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

history-service/internal/mongorepo/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package mongorepo
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

history-service/internal/service/integration_test.go

@@ -1,6 +1,6 @@
 //go:build integration
 
-package service_test
+package service
 
 import (
 	"context"
@@ -16,7 +16,6 @@ import (
 
 	"github.com/hmchangw/chat/history-service/internal/cassrepo"
 	"github.com/hmchangw/chat/history-service/internal/models"
-	"github.com/hmchangw/chat/history-service/internal/service"
 	"github.com/hmchangw/chat/pkg/model"
 	"github.com/hmchangw/chat/pkg/msgbucket"
 	"github.com/hmchangw/chat/pkg/natsrouter"
@@ -139,7 +138,7 @@ func TestEditMessage_Integration(t *testing.T) {
 	session := setupCassandra(t)
 	repo := cassrepo.NewRepository(session, msgbucket.New(24*time.Hour), 365)
 	pub := &recordingPublisher{}
-	svc := service.New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
+	svc := New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
 
 	sender := models.Participant{ID: "u1", Account: "alice"}
 	roomID := "r-integ"
@@ -202,7 +201,7 @@ func TestDeleteMessage_Integration(t *testing.T) {
 	session := setupCassandra(t)
 	repo := cassrepo.NewRepository(session, msgbucket.New(24*time.Hour), 365)
 	pub := &recordingPublisher{}
-	svc := service.New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
+	svc := New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
 
 	sender := models.Participant{ID: "u1", Account: "alice"}
 	roomID := "r-del-integ"
@@ -262,7 +261,7 @@ func TestDeleteMessage_ParentWithReplies_NoCascade(t *testing.T) {
 	session := setupCassandra(t)
 	repo := cassrepo.NewRepository(session, msgbucket.New(24*time.Hour), 365)
 	pub := &recordingPublisher{}
-	svc := service.New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
+	svc := New(repo, alwaysSubscribedRepo{}, stubRoomRepo{}, pub, nil, 730*24*time.Hour)
 
 	sender := models.Participant{ID: "u1", Account: "alice"}
 	roomID := "r-parent-cascade"

history-service/internal/service/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package service
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

inbox-worker/integration_test.go

@@ -13,15 +13,13 @@ import (
 	"github.com/nats-io/nats.go/jetstream"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	natsmod "github.com/testcontainers/testcontainers-go/modules/nats"
 	"go.mongodb.org/mongo-driver/v2/bson"
 	"go.mongodb.org/mongo-driver/v2/mongo"
 
 	"github.com/hmchangw/chat/pkg/model"
 	"github.com/hmchangw/chat/pkg/stream"
 	"github.com/hmchangw/chat/pkg/subject"
 	"github.com/hmchangw/chat/pkg/testutil"
-	"github.com/hmchangw/chat/pkg/testutil/testimages"
 )
 
 func setupMongo(t *testing.T) *mongo.Database {
@@ -577,20 +575,13 @@ func TestHandleMemberAdded_DM_PersistsRemoteCounterpartSub(t *testing.T) {
 	assert.False(t, bobSub.IsSubscribed, "DM does not set IsSubscribed=true")
 }
 
-// setupNATS starts a NATS container with JetStream enabled and returns a
-// JetStream client tied to the test's lifetime.
+// setupNATS connects to the process-shared NATS (JetStream enabled in
+// testutil) and returns a JetStream client tied to the test's lifetime.
 func setupNATS(t *testing.T) (context.Context, jetstream.JetStream) {
 	t.Helper()
 	ctx := context.Background()
 
-	c, err := natsmod.Run(ctx, testimages.NATS)
-	require.NoError(t, err)
-	t.Cleanup(func() { _ = c.Terminate(ctx) })
-
-	url, err := c.ConnectionString(ctx)
-	require.NoError(t, err)
-
-	nc, err := nats.Connect(url)
+	nc, err := nats.Connect(testutil.NATS(t))
 	require.NoError(t, err)
 	t.Cleanup(func() { nc.Close() })
 

inbox-worker/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package main
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

message-worker/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package main
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

notification-worker/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package main
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

pkg/minioutil/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package minioutil
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }

pkg/mongoutil/main_test.go

@@ -0,0 +1,11 @@
+//go:build integration
+
+package mongoutil
+
+import (
+	"testing"
+
+	"github.com/hmchangw/chat/pkg/testutil"
+)
+
+func TestMain(m *testing.M) { testutil.RunTests(m) }