go-tddSafety --Repository ShareFavorite skill

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

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

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:

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:

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

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