go-tdd

When to Use

• Starting implementation of any new feature (TDD = write test FIRST)
• Adding tests for existing code
• Creating mocks for domain ports
• Setting up integration tests with real databases
• Writing contract tests between services (producer/consumer)
• Reviewing test quality

---

Critical Patterns

Pattern	Rule
Test FIRST	Write the failing test before writing production code. Always.
Red → Green → Refactor	Fail → pass → clean up. Never skip a step.
Table-driven tests	Go convention: use []struct for test cases
Mocks via interfaces	No mock frameworks needed — domain ports ARE the mock boundary
Test file colocation	service.go → service_test.go in same package
Integration tests tagged	Use //go:build integration tag
No test pollution	Each test is independent, no shared mutable state

---

The TDD Cycle

1. RED    — Write a test that describes the desired behavior. Run it. It MUST fail.
2. GREEN  — Write the MINIMUM code to make the test pass. Nothing more.
3. REFACTOR — Clean up the code while keeping tests green.
4. REPEAT

When Writing Code with AI (IMPORTANT)

1. DESCRIBE the behavior you want as a test
2. AI writes the failing test
3. Run it — confirm RED
4. AI writes the implementation
5. Run it — confirm GREEN
6. AI refactors if needed
7. Run it — confirm still GREEN

---

Unit Tests

Table-Driven Pattern

See assets/service_test.go

Mock Pattern (No Framework Needed)

See assets/mock_test.go

Domain Entity Tests

See assets/entity_test.go

Handler Tests (httptest)

See assets/http_test.go

---

Integration Tests (Testcontainers)

Unit vs Integration

Aspect	Unit Test	Integration Test
Database	In-memory implementation	Real PostgreSQL via testcontainers
External services	Mocked interfaces	Real or contract-verified
Speed	Milliseconds	Seconds (container startup)
Build tag	None	//go:build integration
File suffix	_test.go	_integration_test.go
When to run	Always (go test ./...)	CI + explicit (go test -tags=integration)

Testcontainers Pattern

Every integration test file follows this structure:

1. Build tag //go:build integration on line 1
2. TestMain function that starts the container and runs migrations
3. Shared pool variable for all tests in the package
4. Table-driven tests using the real pool
5. Cleanup in TestMain (container terminates automatically)

See assets/postgres_setup_test.go for the TestMain pattern with PostgreSQL container setup.

See assets/repository_integration_test.go for repository integration test examples.

Repository Test Strategy

Two implementations, two purposes:

Layer	Implementation	Used By	What It Validates
In-memory	repository/memory.go	Unit tests + local dev without Docker	Domain logic, application flow
PostgreSQL	repository/postgres.go	Integration tests (testcontainers) + deployed envs	Real SQL, constraints, indexes

See assets/repository_test_strategy.go

See go-repository-pattern skill for in-memory implementation details.

---

Contract Tests

Contract tests verify that service boundaries (API contracts) don't break silently. Two perspectives:

Role	What it tests	Who owns it
Producer	"My API responses match the documented contract"	Service team
Consumer	"I can parse the response the other service returns"	Client team

Contract tests run against a real HTTP server (httptest) with in-memory repos — they validate the shape of requests/responses, NOT business logic.

See assets/contract_producer_test.go for producer contract test pattern.

See assets/contract_consumer_test.go for consumer contract test pattern.

Handler Integration Tests

Handler integration tests use httptest.NewServer with the real Gin router, real service, and real (or in-memory) repos. They test the full HTTP stack including:

• JSON serialization/deserialization
• HTTP status codes for all error paths
• Request validation (binding tags)
• Response envelope format ({"data": ...} / {"error": ...})

See assets/handler_integration_test.go for the full handler integration test pattern.

---

Decision Tree

Testing domain logic (entity, value object)?
  → Unit test with table-driven pattern

Testing a use case / application service?
  → Unit test with mocked ports (in-memory repo)

Testing a repository method against real SQL?
  → Integration test with testcontainers

Testing a handler's HTTP contract?
  → Contract test with httptest (in-memory repo)

Testing cross-service communication?
  → Consumer contract test (parse expected responses)

Testing migrations work?
  → Integration test: run migrations, verify schema

Testing full HTTP stack (handler → service → repo)?
  → Handler integration test with httptest

---

Test Organization

internal/booking/
  domain/
    entity.go
    entity_test.go           # Unit tests — pure domain logic
    port.go
  application/
    service.go
    service_test.go          # Unit tests — use cases with in-memory repos
    mock_test.go             # Mock implementations for non-repo ports
  infrastructure/
    repository/
      memory.go              # In-memory implementation
      memory_test.go         # Unit tests — verify in-memory behavior
      postgres.go            # PostgreSQL implementation
      postgres_integration_test.go  # Integration — real DB via testcontainers
    handler/
      http.go
      http_test.go           # HTTP handler tests — httptest
      http_contract_test.go  # Contract tests — response shape validation

---

Assets

File	Description
assets/service_test.go	Table-driven unit test for application service
assets/mock_test.go	Manual mock implementation via interfaces
assets/entity_test.go	Domain entity unit tests
assets/http_test.go	Handler tests with httptest
assets/postgres_setup_test.go	TestMain: start PostgreSQL container, run migrations, expose pool
assets/repository_integration_test.go	Repository integration tests with real PostgreSQL
assets/repository_test_strategy.go	In-memory vs PostgreSQL test strategy
assets/contract_producer_test.go	Producer contract test: verify API response shape
assets/contract_consumer_test.go	Consumer contract test: parse responses from other services
assets/handler_integration_test.go	Full HTTP handler integration test with httptest
assets/Makefile	Test-related Makefile targets

---

Commands

# Run all unit tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific package
go test -v ./internal/booking/application/...

# Run integration tests only
go test -v -tags=integration ./...

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific test
go test -v -run TestBookingService_CreateBooking ./internal/booking/application/

# Race detection
go test -race ./...

# Testcontainers dependency
go get github.com/testcontainers/testcontainers-go
go get github.com/testcontainers/testcontainers-go/modules/postgres

Makefile Targets

See assets/Makefile

---

Anti-Patterns

Don't	Do
Write code first, tests later	Write test FIRST (red), then code (green)
Use testify/mock or mockgen	Use manual mocks via interfaces — simpler, explicit
Test implementation details	Test behavior — inputs and outputs
Shared state between tests	Each test creates its own fixtures
Skip integration tests	Use testcontainers — real DB, real behavior
One giant test function	Table-driven tests with descriptive names
t.Log for assertions	Use t.Errorf / t.Fatalf with clear messages
Skip contract tests for APIs	Validate response shapes to catch drift early