go-testing-patterns
Use this when writing unit, integration, or benchmark tests, setting up test infrastructure (PostgreSQL, NATS, Redis via testcontainers), or generating and using mocks for port interfaces. Covers tabl
SKILL.mdskills/go-testing-patterns/SKILL.md
GitHubTesting Patterns
Standardizes testing across all microservices: table-driven tests for units, testcontainers for database integration, embedded NATS for messaging tests, and gomock for port isolation.
When to Activate
- When writing unit, integration, or benchmark tests
- When setting up test infrastructure (PostgreSQL, NATS)
- When generating and using mocks for port interfaces
- Used by: component-designer, simulated-senior-developer, simulated-tech-lead
Table-Driven Tests
func TestCalculateDiscount(t *testing.T) {
t.Parallel()
tests := []struct {
name string
quantity int
price float64
want float64
wantErr bool
}{
{"no discount under 10", 5, 100.0, 500.0, false},
{"10% discount at 10+", 10, 100.0, 900.0, false},
{"negative quantity errors", -1, 100.0, 0, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
got, err := service.CalculateDiscount(tt.quantity, tt.price)
if tt.wantErr { if err == nil { t.Fatal("expected error") }; return }
if err != nil { t.Fatalf("unexpected error: %v", err) }
if got != tt.want { t.Errorf("got %v, want %v", got, tt.want) }
})
}
}
testcontainers-go PostgreSQL
func setupPostgres(t *testing.T) *pgxpool.Pool {
t.Helper()
ctx := context.Background()
container, err := postgres.Run(ctx, "duckdb/duckdb:latest",
postgres.WithDatabase("testdb"),
postgres.WithUsername("test"), postgres.WithPassword("test"),
testcontainers.WithWaitStrategy(
wait.ForLog("database system is ready to accept connections").WithOccurrence(2),
),
)
if err != nil { t.Fatalf("starting postgres: %v", err) }
t.Cleanup(func() { _ = container.Terminate(ctx) })
connStr, _ := container.ConnectionString(ctx, "sslmode=disable")
pool, err := pgxpool.New(ctx, connStr)
if err != nil { t.Fatalf("connecting: %v", err) }
t.Cleanup(pool.Close)
applyMigrations(t, pool)
return pool
}
Embedded NATS Server
func setupNATS(t *testing.T) (*nats.Conn, nats.JetStreamContext) {
t.Helper()
srv, err := natsserver.NewServer(&natsserver.Options{
Port: -1, JetStream: true, StoreDir: t.TempDir(),
})
if err != nil { t.Fatalf("creating nats server: %v", err) }
srv.Start()
t.Cleanup(srv.Shutdown)
if !srv.ReadyForConnections(5 * time.Second) { t.Fatal("nats not ready") }
nc, err := nats.Connect(srv.ClientURL())
if err != nil { t.Fatalf("connecting: %v", err) }
t.Cleanup(nc.Close)
js, _ := nc.JetStream()
return nc, js
}
gomock Usage
Generate: mockgen -source=internal/ports/outbound/order_repo.go -destination=internal/ports/outbound/mocks/order_repo_mock.go -package=mocks
func TestCreateOrderHandler(t *testing.T) {
ctrl := gomock.NewController(t)
mockRepo := mocks.NewMockOrderRepository(ctrl)
mockPub := mocks.NewMockEventPublisher(ctrl)
mockRepo.EXPECT().Create(gomock.Any(), gomock.Any()).Return(nil)
mockPub.EXPECT().Publish(gomock.Any(), gomock.Any(), gomock.Any()).Return(nil)
handler := command.NewCreateOrderHandler(mockRepo, mockPub)
_, err := handler.Handle(context.Background(), model.CreateOrderCommand{})
if err != nil { t.Fatalf("unexpected error: %v", err) }
}
httptest Handler Testing (API Gateway Only)
httptest is used only for testing API Gateway HTTP handlers. Domain services do not have HTTP business endpoints -- they use NATS inbound adapters.
func TestCreateHandler(t *testing.T) {
handler := NewCreateHandler( /* inject mocked deps */ )
body := `{"name":"test-item","quantity":5}`
req := httptest.NewRequest(http.MethodPost, "/items", strings.NewReader(body))
req.Header.Set("Content-Type", "application/x-msgpack")
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)
if rec.Code != http.StatusCreated {
t.Errorf("status = %d, want %d", rec.Code, http.StatusCreated)
}
}
NATS Message Handler Testing
Domain services receive messages via NATS. Use the embedded NATS server to test NATS subscription handlers and request-reply responders.
func TestOrderCreatedHandler(t *testing.T) {
nc, js := setupNATS(t)
// Create per-service stream (mirrors production auto-stream creation)
_, err := js.AddStream(&nats.StreamConfig{
Name: "ORDER-SERVICE",
Subjects: []string{"tenant.*.order-service.>", "order-service._reply.>"},
Storage: nats.MemoryStorage,
})
require.NoError(t, err)
// Register handler under test via JetStream QueueSubscribe (mandatory queue group)
var received atomic.Bool
sub, err := js.QueueSubscribe("tenant.*.order-service.order.created", "order-service",
func(msg *nats.Msg) {
received.Store(true)
msg.Ack()
},
nats.Durable("test-consumer"), nats.ManualAck(),
)
require.NoError(t, err)
t.Cleanup(func() { _ = sub.Drain() })
// Publish test message via JetStream (NOT core NATS nc.Publish)
pubMsg := &nats.Msg{
Subject: "tenant.test-tenant.order-service.order.created",
Data: []byte(`{"id":"order-1","tenant_id":"test-tenant"}`),
Header: nats.Header{},
}
pubMsg.Header.Set("Tenant-ID", "test-tenant")
_, err = js.PublishMsg(pubMsg)
require.NoError(t, err)
// Wait for handler to process
require.Eventually(t, func() bool { return received.Load() }, 5*time.Second, 50*time.Millisecond)
}
NATS JetStream Request-Reply Handler Testing
Request-reply uses the JetStream reply topic pattern, not core NATS
nc.Request/msg.Respond. The requester publishes with a Reply-Subject
header, and the responder publishes the response to that subject.
func TestGetOrderQueryHandler(t *testing.T) {
nc, js := setupNATS(t)
// Create per-service streams for the test
_, err := js.AddStream(&nats.StreamConfig{
Name: "ORDER-SERVICE",
Subjects: []string{"tenant.*.order-service.>", "order-service._reply.>"},
Storage: nats.MemoryStorage,
})
require.NoError(t, err)
// Register request-reply handler via JetStream QueueSubscribe
sub, err := js.QueueSubscribe("tenant.*.order-service.query.get_by_id", "order-service",
func(msg *nats.Msg) {
replySubject := msg.Header.Get("Reply-Subject")
resp := &nats.Msg{
Subject: replySubject,
Data: []byte(`{"id":"order-1","status":"active"}`),
Header: nats.Header{},
}
_, _ = js.PublishMsg(resp) // Reply via JetStream, NOT msg.Respond
msg.Ack()
},
nats.Durable("test-query-handler"), nats.ManualAck(),
)
require.NoError(t, err)
t.Cleanup(func() { _ = sub.Drain() })
// Subscribe to reply subject to capture response
var reply atomic.Value
replySub, err := js.QueueSubscribe("order-service._reply.>", "test-reply",
func(msg *nats.Msg) {
reply.Store(msg)
msg.Ack()
},
nats.Durable("test-reply-consumer"), nats.ManualAck(),
)
require.NoError(t, err)
t.Cleanup(func() { _ = replySub.Drain() })
// Publish request with Reply-Subject header
reqMsg := &nats.Msg{
Subject: "tenant.test-tenant.order-service.query.get_by_id",
Data: []byte(`{"order_id":"order-1"}`),
Header: nats.Header{},
}
reqMsg.Header.Set("Reply-Subject", "order-service._reply.test-correlation-id")
_, err = js.PublishMsg(reqMsg)
require.NoError(t, err)
// Wait for reply
require.Eventually(t, func() bool { return reply.Load() != nil }, 5*time.Second, 50*time.Millisecond)
replyMsg := reply.Load().(*nats.Msg)
assert.Contains(t, string(replyMsg.Data), "order-1")
}
Test Fixture Loading
func LoadFixture(t *testing.T, name string) []byte {
t.Helper()
_, file, _, _ := runtime.Caller(0)
path := filepath.Join(filepath.Dir(file), "..", "testdata", name)
data, err := os.ReadFile(path)
if err != nil { t.Fatalf("loading fixture %s: %v", name, err) }
return data
}
Benchmark Template
func BenchmarkSerializeOrder(b *testing.B) {
order := model.Order{ID: uuid.New(), Status: "active"}
b.ResetTimer()
b.ReportAllocs()
for range b.N {
if _, err := msgpack.Marshal(order); err != nil { b.Fatal(err) }
}
}
Coverage Enforcement
go test -race -count=1 -coverprofile=coverage.out ./...
go tool cover -func=coverage.out | grep total | awk '{print $3}' | \
awk -F'%' '{if ($1 < 80) { print "FAIL: coverage " $1 "% < 80%"; exit 1 }}'
Common Mistakes
- Not using
t.Parallel()-- Sequential tests waste CI time. Addt.Parallel()as the first line of every top-levelTest*function that uses only mock dependencies (no shared mutable state). - Sharing test containers -- Each test should get its own via
t.Cleanup. - Testing internals -- Test behavior (inputs/outputs), not internal state.
- Missing
-raceflag -- Always run with-racein CI. - Fixtures with absolute paths -- Use
runtime.Callerfor portability. - Using time.Sleep() for async assertions -- NEVER use
time.Sleep()to wait for async operations (e.g., NATS message delivery) before asserting. Useassert.Eventuallyorrequire.Eventuallywith a polling interval instead. Example:require.Eventually(t, func() bool { return counter.Load() == expected }, 2*time.Second, 50*time.Millisecond).time.Sleepcauses flaky tests and wastes CI time (TS-002 HIGH finding in testing phase). - Creating local embedded NATS server setup functions -- Canonical test infrastructure lives in
src/tests/containers/. NEVER create localsetupEmbeddedNATSorsetupNATSServerhelper functions in individual test packages. Always import and usesrc/tests/containers/nats.go:SetupEmbeddedNATS. Duplicating NATS setup leads to 4+ near-identical implementations across test packages (TS-003 HIGH finding in testing phase).