golang-testing

name	golang-testing
description	Production-ready testing practices in Go: table-driven tests, named subtests, test isolation, mock generation/design, integration tests isolation using build tags, and avoiding flakiness. Apply when writing, reviewing, or debugging Go tests.
user-invocable	true
license	MIT
compatibility	Designed for Go testing suites.

Go Testing Best Practices

This skill outlines guidelines for writing maintainable, fast, and deterministic tests in Go projects.

1. Table-Driven Tests (Idiomatic Go)

Always use table-driven tests for multiple inputs/scenarios. Each scenario MUST have a descriptive name field, which is passed to t.Run.

func TestAdd(t *testing.T) {
    tests := []struct {
        name     string
        a, b     int
        expected int
    }{
        {
            name:     "positive numbers",
            a:        2,
            b:        3,
            expected: 5,
        },
        {
            name:     "negative and positive",
            a:        -1,
            b:        1,
            expected: 0,
        },
        {
            name:     "both negative",
            a:        -2,
            b:        -3,
            expected: -5,
        },
    }

    for _, tt := range tests {
        // Capture range variable to avoid concurrency issues in loops
        tt := tt
        t.Run(tt.name, func(t *testing.T) {
            got := Add(tt.a, tt.b)
            if got != tt.expected {
                t.Errorf("Add(%d, %d) = %d; want %d", tt.a, tt.b, got, tt.expected)
            }
        })
    }
}

---

2. Test Parallelism

• Independent unit tests SHOULD run in parallel.
• Call t.Parallel() inside the main test and also inside individual t.Run subtests.
• Caution: Always capture the range variable (e.g., tt := tt) at the top of the loop before running subtests in parallel to prevent goroutines from referring to the last item in the slice.

---

3. Mocking & Dependencies

1. Mock Interfaces, Not Structs:
   • Write functions to accept interfaces, enabling easy mocking in tests.
2. Minimalist Mocks:
   • Prefer hand-written mock structs implementing only the needed methods, or use code generation tools like mockery or go-mock (avoid manual complex mocks that break on interface changes).
3. Use Test Cleanups:
   • Use t.Cleanup(func() { ... }) instead of defer inside subtests for cleaning up test databases, directories, or mocks. t.Cleanup runs even if the test panics or fails early.

---

4. Integration vs. Unit Tests

1. Keep Unit Tests Fast:
   • Unit tests should execute in < 10ms and run without network or filesystem dependencies.
2. Isolate Integration Tests:
   • Separate integration tests (which rely on databases, AWS, or local networks) using build tags:

     //go:build integration
     
     package mypackage_test
     

   • Run unit tests with standard go test ./....
   • Run integration tests explicitly with go test -tags=integration ./....

---

5. Avoiding Test Flakiness

1. No Shared State:
   • Ensure tests are completely independent and don't share global mutable state.
2. Order Independence:
   • Tests must run successfully in any order. Verify with:

     go test -shuffle=on ./...
     

3. Goroutine Leak Check:
   • Use go.uber.org/goleak to verify that background goroutines spawned in tests are properly closed before exiting.