---

name: go-test description: > Go testing patterns and best practices. Load when writing or running Go tests. Triggers: running tests, writing test files, test coverage, benchmarks, integration tests, table-driven tests, mocking, fixtures, or asking about Go testing patterns. license: MIT compatibility: opencode

Go Testing

Run and write tests for Go projects following best practices.

When This Skill MUST Be Used

ALWAYS invoke this skill when the user's request involves ANY of these:

• Running go test or asking to run tests
• Writing or modifying *_test.go files
• Setting up integration tests with databases
• Test coverage analysis
• Benchmarking Go code
• Mocking or test fixtures
• Table-driven tests
• Race condition detection
• Test structure (GIVEN-WHEN-THEN)

If you're about to run or write Go tests, STOP and use this skill first.

Critical Safety Rules

NEVER:

• Run integration tests without checking for required env vars
• Skip the -race flag in CI/CD pipelines
• Leave test containers running after tests
• Commit code with failing tests
• Use require/Fatal inside goroutines (causes panic)
• Share mocks, loggers, or DB connections between parallel tests

ALWAYS:

• Use t.Parallel() for independent tests AND subtests
• Clean up test resources with t.Cleanup()
• Use build tags to separate unit and integration tests
• Check test coverage for new code
• Mark helper functions with t.Helper()

Quick Reference

---

Test Structure: GIVEN-WHEN-THEN

• GIVEN: Setup and preconditions (use require - stop if setup fails)
• WHEN: Single action being tested (use require - stop if action fails)
• THEN: Assertions on results (use assert - see all failures)

Critical: Only ONE WHEN section per test. Multiple behaviors = multiple tests.

require vs assert

Goroutine Warning: Never use require/Fatal inside goroutines, HTTP handlers, or callbacks - causes "FailNow called from non-test goroutine" panic.

---

Parallel Execution

• Always use t.Parallel() in tests AND subtests
• Each test creates its own fixture - no shared state
• Subtests must NOT access parent test variables

Forbidden Sharing:

• Loggers, database connections, singletons
• File handles, network ports
• Mock expectations defined in parent scope

Acceptable Sharing:

• Read-only table data in table-driven tests
• Global constants, types, and functions

---

File Naming

Default: Use public tests. Add private tests only for internal invariants or combinatorial explosion.

Test Naming

• Functions: Test<Type>_<Method> (e.g., TestUserService_CreateUser)
• Subtests: Short, descriptive (e.g., "with valid input", "returns error")

---

Table-Driven Tests

When to Use

• Simple data variations (primitives only)
• Boundary conditions and validation
• 3-4 fields maximum in table struct

The Simplicity Test

"Can I understand what each test case does by looking at one line in the table?"

If NO, use separate tests instead.

Anti-patterns (Never Put in Tables)

---

Fixture Pattern

Copytype fixture struct {
    ctx      context.Context
    mockRepo *MockRepository
    sut      *Service
}

func newFixture(t *testing.T) *fixture {
    t.Helper()
    ctrl := gomock.NewController(t)
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    t.Cleanup(cancel)
    
    mockRepo := NewMockRepository(ctrl)
    return &fixture{
        ctx:      ctx,
        mockRepo: mockRepo,
        sut:      NewService(mockRepo),
    }
}

---

Mocking

• Define interfaces in interfaces.go
• Add //go:generate mockgen directive
• Store mocks in mock_test.go with package foo_test
• gomock.Any() when values don't matter
• gomock.Eq() for exact matching in happy path
• Create new mock controller per test/subtest

---

Must Constructor Pattern

For test helpers that panic on error (never in production):

Copy// Production: returns error
func NewCategoryID(value string) (CategoryID, error)

// Tests only: panics on error
func MustCategoryID(value string) CategoryID {
    id, err := NewCategoryID(value)
    if err != nil {
        panic(err)
    }
    return id
}

Standard library examples: regexp.MustCompile, template.Must

---

Deterministic Tests

Inject all nondeterminism:

---

Contract Testing (Marshal/Unmarshal)

• Use raw JSON strings as the "contract"
• Don't use internal types for both encode and decode
• Use testify.JSONEq() for comparison
• Store JSON contracts in testdata/ directory

---

Testing Conversion Layers

What to test in HTTP/gRPC handlers:

1. Request unmarshaling and argument passing
2. Error translation (domain errors -> protocol errors)
3. Response marshaling

Pattern: Mock domain layer, verify exact arguments, verify error codes.

---

Coverage

---

Running Tests

Basic Commands

Copy# Unit tests only
go test ./...

# Unit tests with verbose output
go test -v ./...

# Unit tests with coverage
go test -cover ./...

# Unit tests with coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Running Single Tests

Copy# Run specific test by name
go test -v -run TestOrderRepository ./internal/infra/mysqlrepo/...

# Run tests matching pattern
go test -v -run "TestOrder.*" ./...

# Run specific subtest
go test -v -run "TestOrderRepository/creates_order" ./...

---

Integration Tests

Integration tests typically use build tags to separate from unit tests:

Copy# Run integration tests (requires database)
go test -tags=integration -v ./...

# Run integration tests for specific package
go test -tags=integration -v ./internal/infra/mysqlrepo/...

# With database DSN
TEST_MYSQL_DSN="root:pass@tcp(localhost:3306)/testdb?parseTime=true" \
  go test -tags=integration -v ./...

Docker-based Database for Tests

Copy# Start MySQL container
docker run -d --name test-mysql \
  -e MYSQL_ROOT_PASSWORD=pass \
  -e MYSQL_DATABASE=testdb \
  -p 3306:3306 \
  mysql:8

# Wait for MySQL to be ready
until docker exec test-mysql mysqladmin ping -h localhost --silent; do
  sleep 1
done

# Run integration tests
TEST_MYSQL_DSN="root:pass@tcp(localhost:3306)/testdb?parseTime=true" \
  go test -tags=integration -v ./...

# Clean up
docker rm -f test-mysql

Integration Test Setup

Copy//go:build integration

package mysqlrepo_test

import (
    "os"
    "testing"
)

func TestMain(m *testing.M) {
    dsn := os.Getenv("TEST_MYSQL_DSN")
    if dsn == "" {
        // Skip integration tests if DSN not set
        os.Exit(0)
    }
    
    // Setup database connection
    // Run migrations if needed
    
    code := m.Run()
    
    // Cleanup
    
    os.Exit(code)
}

---

Coverage

Copy# Generate coverage profile
go test -coverprofile=coverage.out ./...

# View coverage in terminal
go tool cover -func=coverage.out

# View coverage in browser
go tool cover -html=coverage.out

# Coverage for specific packages
go test -coverprofile=coverage.out -coverpkg=./internal/... ./...

---

Race Detection

Copy# Run tests with race detector
go test -race ./...

# Race detection with specific test
go test -race -run TestConcurrentAccess ./...

---

Benchmarks

Copy# Run all benchmarks
go test -bench=. ./...

# Run specific benchmark
go test -bench=BenchmarkOrderCreation ./internal/domain/order/...

# Benchmarks with memory allocation stats
go test -bench=. -benchmem ./...

# Run benchmark multiple times
go test -bench=. -count=5 ./...

---

Test Caching

Copy# Force re-run (disable cache)
go test -count=1 ./...

# Clean test cache
go clean -testcache

---

Makefile Targets

Copy.PHONY: test test-unit test-integration test-coverage

test: test-unit

test-unit:
	go test -v -race ./...

test-integration:
	go test -tags=integration -v ./...

test-coverage:
	go test -coverprofile=coverage.out ./...
	go tool cover -html=coverage.out -o coverage.html

---

Troubleshooting

---

Example Requests