Golang Testing

Provides a comprehensive guide for writing production-ready Golang tests. Covers table-driven tests, test suites with testify, mocks, unit tests, integration...

Security Scan

The skill is internally consistent with its stated purpose of guiding Go tests; it installs and uses gotests as expected and contains realistic examples, though integration examples assume Docker/docker-compose is available even though those binaries are not declared.

Purpose & Capability

Name/description (Go testing) align with requested binaries and install (go + gotests). The install uses a public Go package (gotests) which is appropriate. Minor inconsistency: integration examples call docker-compose and expect Docker services, but Docker/docker-compose are not listed under required binaries or install.

Instruction Scope

SKILL.md is an instruction-only skill and stays within testing-related actions (scaffold tests with gotests, run tests, use goleak, use httptest, mock patterns). It includes examples that run system commands (exec.Command to launch docker-compose) and read local fixture files — expected for integration testing but these are system-level operations that require Docker and local files. The Audit mode mentions launching parallel sub-agents (logical decomposition) — this grants the agent operational discretion but is within the testing domain.

Install Mechanism

Install spec uses `go` to fetch github.com/cweill/gotests/gotests@latest and creates the gotests binary — a standard, traceable Go install. No arbitrary downloads or extract-from-unknown-URLs are used.

Credentials

The skill declares no required environment variables or credentials. Examples use fixed test credentials (e.g., postgres://test:test@localhost:5433/testdb) for local fixtures, which is normal for test setups and not a secret exfiltration risk.

Persistence & Privilege

always:false and normal autonomous invocation settings. The skill does not request persistent presence or attempt to modify other skills or system-wide agent settings.

Assessment

This skill appears to be what it says: a Go testing guide that scaffolds tests with gotests and provides examples for unit and integration testing. Before installing, note: (1) the skill installs/uses gotests (from a public Go package) — review that package if you prefer to vet dependencies; (2) several integration examples run docker-compose and expect Docker services; the skill does not declare Docker/docker-compose as required binaries, so ensure your environment has Docker if you plan to use integration features; (3) integration examples will start containers and open ports on localhost (e.g., Postgres on 5433), so be aware of resource and network implications; (4) the skill can run system commands (exec.Command examples) when used by an agent — only grant run privileges to agents you trust. If you want to be stricter, add docker/docker-compose to required binaries or avoid running integration examples on sensitive hosts.

Persona: You are a Go engineer who treats tests as executable specifications. You write tests to constrain behavior, not to hit coverage targets.

Thinking mode: Use ultrathink for test strategy design and failure analysis. Shallow reasoning misses edge cases and produces brittle tests that pass today but break tomorrow.

Modes:

• Write mode — generating new tests for existing or new code. Work sequentially through the code under test; use gotests to scaffold table-driven tests, then enrich with edge cases and error paths.
• Review mode — reviewing a PR's test changes. Focus on the diff: check coverage of new behaviour, assertion quality, table-driven structure, and absence of flakiness patterns. Sequential.
• Audit mode — auditing an existing test suite for gaps, flakiness, or bad patterns (order-dependent tests, missing t.Parallel(), implementation-detail coupling). Launch up to 3 parallel sub-agents split by concern: (1) unit test quality and coverage gaps, (2) integration test isolation and build tags, (3) goroutine leaks and race conditions.
• Debug mode — a test is failing or flaky. Work sequentially: reproduce reliably, isolate the failing assertion, trace the root cause in production code or test setup.

Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-testing skill takes precedence.

Go Testing Best Practices

This skill guides the creation of production-ready tests for Go applications. Follow these principles to write maintainable, fast, and reliable tests.

Best Practices Summary

1. Table-driven tests MUST use named subtests -- every test case needs a name field passed to t.Run
2. Integration tests MUST use build tags (//go:build integration) to separate from unit tests
3. Tests MUST NOT depend on execution order -- each test MUST be independently runnable
4. Independent tests SHOULD use t.Parallel() when possible
5. NEVER test implementation details -- test observable behavior and public API contracts
6. Packages with goroutines SHOULD use goleak.VerifyTestMain in TestMain to detect goroutine leaks
7. Use testify as helpers, not a replacement for standard library
8. Mock interfaces, not concrete types
9. Keep unit tests fast (< 1ms), use build tags for integration tests
10. Run tests with race detection in CI
11. Include examples as executable documentation

Test Structure and Organization

File Conventions

// package_test.go - tests in same package (white-box, access unexported)
package mypackage

// mypackage_test.go - tests in test package (black-box, public API only)
package mypackage_test

Naming Conventions

func TestAdd(t *testing.T) { ... }              // function test
func TestMyStruct_MyMethod(t *testing.T) { ... } // method test
func BenchmarkAdd(b *testing.B) { ... }          // benchmark
func ExampleAdd() { ... }                        // example

Table-Driven Tests

Table-driven tests are the idiomatic Go way to test multiple scenarios. Always name each test case.

func TestCalculatePrice(t *testing.T) {
    tests := []struct {
        name     string
        quantity int
        unitPrice float64
        expected  float64
    }{
        {
            name:      "single item",
            quantity:  1,
            unitPrice: 10.0,
            expected:  10.0,
        },
        {
            name:      "bulk discount - 100 items",
            quantity:  100,
            unitPrice: 10.0,
            expected:  900.0, // 10% discount
        },
        {
            name:      "zero quantity",
            quantity:  0,
            unitPrice: 10.0,
            expected:  0.0,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got := CalculatePrice(tt.quantity, tt.unitPrice)
            if got != tt.expected {
                t.Errorf("CalculatePrice(%d, %.2f) = %.2f, want %.2f",
                    tt.quantity, tt.unitPrice, got, tt.expected)
            }
        })
    }
}

Unit Tests

Unit tests should be fast (< 1ms), isolated (no external dependencies), and deterministic.

Testing HTTP Handlers

Use httptest for handler tests with table-driven patterns. See HTTP Testing for examples with request/response bodies, query parameters, headers, and status code assertions.

Goroutine Leak Detection with goleak

Use go.uber.org/goleak to detect leaking goroutines, especially for concurrent code:

import (
    "testing"
    "go.uber.org/goleak"
)

func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m)
}

To exclude specific goroutine stacks (for known leaks or library goroutines):

func TestMain(m *testing.M) {
    goleak.VerifyTestMain(m,
        goleak.IgnoreCurrent(),
    )
}

Or per-test:

func TestWorkerPool(t *testing.T) {
    defer goleak.VerifyNone(t)
    // ... test code ...
}

testing/synctest for Deterministic Goroutine Testing

Experimental: testing/synctest is not yet covered by Go's compatibility guarantee. Its API may change in future releases. For stable alternatives, use clockwork (see Mocking).

testing/synctest (Go 1.24+) provides deterministic time for concurrent code testing. Time advances only when all goroutines are blocked, making ordering predictable.

When to use synctest instead of real time:

• Testing concurrent code with time-based operations (time.Sleep, time.After, time.Ticker)
• When race conditions need to be reproducible
• When tests are flaky due to timing issues

import (
    "testing"
    "time"
    "testing/synctest"
    "github.com/stretchr/testify/assert"
)

func TestChannelTimeout(t *testing.T) {
    synctest.Run(func(t *testing.T) {
        is := assert.New(t)

        ch := make(chan int, 1)
        go func() {
            time.Sleep(50 * time.Millisecond)
            ch <- 42
        }()

        select {
        case v := <-ch:
            is.Equal(42, v)
        case <-time.After(100 * time.Millisecond):
            t.Fatal("timeout occurred")
        }
    })
}

Key differences in synctest:

• time.Sleep advances synthetic time instantly when the goroutine blocks
• time.After fires when synthetic time reaches the duration
• All goroutines run to blocking points before time advances
• Test execution is deterministic and repeatable

Test Timeouts

For tests that may hang, use a timeout helper that panics with caller location. See Helpers.

Benchmarks

→ See samber/cc-skills-golang@golang-benchmark skill for advanced benchmarking: b.Loop() (Go 1.24+), benchstat, profiling from benchmarks, and CI regression detection.

Write benchmarks to measure performance and detect regressions:

func BenchmarkStringConcatenation(b *testing.B) {
    b.Run("plus-operator", func(b *testing.B) {
        for i := 0; i < b.N; i++ {
            result := "a" + "b" + "c"
            _ = result
        }
    })

    b.Run("strings.Builder", func(b *testing.B) {
        for i := 0; i < b.N; i++ {
            var builder strings.Builder
            builder.WriteString("a")
            builder.WriteString("b")
            builder.WriteString("c")
            _ = builder.String()
        }
    })
}

Benchmarks with different input sizes:

func BenchmarkFibonacci(b *testing.B) {
    sizes := []int{10, 20, 30}
    for _, size := range sizes {
        b.Run(fmt.Sprintf("n=%d", size), func(b *testing.B) {
            b.ReportAllocs()
            for i := 0; i < b.N; i++ {
                Fibonacci(size)
            }
        })
    }
}

Parallel Tests

Use t.Parallel() to run tests concurrently:

func TestParallelOperations(t *testing.T) {
    tests := []struct {
        name string
        data []byte
    }{
        {"small data", make([]byte, 1024)},
        {"medium data", make([]byte, 1024*1024)},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()
            is := assert.New(t)

            result := Process(tt.data)
            is.NotNil(result)
        })
    }
}

Fuzzing

Use fuzzing to find edge cases and bugs:

func FuzzReverse(f *testing.F) {
    f.Add("hello")
    f.Add("")
    f.Add("a")

    f.Fuzz(func(t *testing.T, input string) {
        reversed := Reverse(input)
        doubleReversed := Reverse(reversed)
        if input != doubleReversed {
            t.Errorf("Reverse(Reverse(%q)) = %q, want %q", input, doubleReversed, input)
        }
    })
}

Examples as Documentation

Examples are executable documentation verified by go test:

func ExampleCalculatePrice() {
    price := CalculatePrice(100, 10.0)
    fmt.Printf("Price: %.2f\n", price)
    // Output: Price: 900.00
}

func ExampleCalculatePrice_singleItem() {
    price := CalculatePrice(1, 25.50)
    fmt.Printf("Price: %.2f\n", price)
    // Output: Price: 25.50
}

Code Coverage

# Generate coverage file
go test -coverprofile=coverage.out ./...

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

# Coverage by function
go tool cover -func=coverage.out

# Total coverage percentage
go tool cover -func=coverage.out | grep total

Integration Tests

Use build tags to separate integration tests from unit tests:

//go:build integration

package mypackage

func TestDatabaseIntegration(t *testing.T) {
    db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        t.Fatal(err)
    }
    defer db.Close()

    // Test real database operations
}

Run integration tests separately:

go test -tags=integration ./...

For Docker Compose fixtures, SQL schemas, and integration test suites, see Integration Testing.

Mocking

Mock interfaces, not concrete types. Define interfaces where consumed, then create mock implementations.

For mock patterns, test fixtures, and time mocking, see Mocking.

Enforce with Linters

Many test best practices are enforced automatically by linters: thelper, paralleltest, testifylint. See the samber/cc-skills-golang@golang-linter skill for configuration and usage.

Cross-References

• -> See samber/cc-skills-golang@golang-stretchr-testify skill for detailed testify API (assert, require, mock, suite)
• -> See samber/cc-skills-golang@golang-database skill (testing.md) for database integration test patterns
• -> See samber/cc-skills-golang@golang-concurrency skill for goroutine leak detection with goleak
• -> See samber/cc-skills-golang@golang-continuous-integration skill for CI test configuration and GitHub Actions workflows
• -> See samber/cc-skills-golang@golang-linter skill for testifylint and paralleltest configuration

Quick Reference

go test ./...                          # all tests
go test -run TestName ./...            # specific test by exact name
go test -run TestName/subtest ./...    # subtests within a test
go test -run 'Test(Add|Sub)' ./...     # multiple tests (regexp OR)
go test -run 'Test[A-Z]' ./...         # tests starting with capital letter
go test -run 'TestUser.*' ./...        # tests matching prefix
go test -run '.*Validation.*' ./...    # tests containing substring
go test -run TestName/. ./...          # all subtests of TestName
go test -run '/(unit|integration)' ./... # filter by subtest name
go test -race ./...                    # race detection
go test -cover ./...                   # coverage summary
go test -bench=. -benchmem ./...       # benchmarks
go test -fuzz=FuzzName ./...           # fuzzing
go test -tags=integration ./...        # integration tests