# Go Testing Patterns

Patterns extracted from the Go standard library source code.

---

## 1. Table-Driven Tests with Subtests

### Source: `src/encoding/json/encode_test.go:405-430`

```go
// src/encoding/json/encode_test.go:405-430
func TestUnsupportedValues(t *testing.T) {
    tests := []struct {
        CaseName
        in any
    }{
        {Name(""), math.NaN()},
        {Name(""), math.Inf(-1)},
        {Name(""), math.Inf(1)},
        {Name(""), pointerCycle},
        {Name(""), pointerCycleIndirect},
        {Name(""), mapCycle},
        {Name(""), sliceCycle},
        {Name(""), recursiveSliceCycle},
    }
    for _, tt := range tests {
        t.Run(tt.Name, func(t *testing.T) {
            if _, err := Marshal(tt.in); err != nil {
                if _, ok := err.(*UnsupportedValueError); !ok {
                    t.Errorf("%s: Marshal error:\n\tgot:  %T\n\twant: %T", tt.Where, err, new(UnsupportedValueError))
                }
            } else {
                t.Errorf("%s: Marshal error: got nil, want non-nil", tt.Where)
            }
        })
    }
}
```

### Source: `src/encoding/json/encode_test.go:270-328` (with inputs and expected outputs)

```go
// src/encoding/json/encode_test.go:270-328
func TestRoundtripStringTag(t *testing.T) {
    tests := []struct {
        CaseName
        in   StringTag
        want string
    }{{
        CaseName: Name("AllTypes"),
        in: StringTag{
            BoolStr:    true,
            IntStr:     42,
            UintptrStr: 44,
            StrStr:     "xzbit",
            NumberStr:  "46",
        },
        want: `{
    "BoolStr": "true",
    "IntStr": "42",
    ...
}`,
    }, {
        CaseName: Name("StringDoubleEscapes"),
        in: StringTag{
            StrStr:    "\b\f\n\r\t\"\\",
            NumberStr: "0",
        },
        want: `{...}`,
    }}
    for _, tt := range tests {
        t.Run(tt.Name, func(t *testing.T) {
            got, err := MarshalIndent(&tt.in, "", "\t")
            if err != nil {
                t.Fatalf("%s: MarshalIndent error: %v", tt.Where, err)
            }
            if got := string(got); got != tt.want {
                t.Fatalf("%s: MarshalIndent:\n\tgot:  %s\n\twant: %s", tt.Where, ...)
            }
            // Verify round-trip
            var s2 StringTag
            if err := Unmarshal(got, &s2); err != nil {
                t.Fatalf("%s: Decode error: %v", tt.Where, err)
            }
            if !reflect.DeepEqual(s2, tt.in) {
                t.Fatalf("%s: Decode:\n\tinput: %s\n\tgot:  %#v\n\twant: %#v", ...)
            }
        })
    }
}
```

### Why

Table-driven tests are Go's signature testing pattern:
1. **All cases visible in one place** — easy to add new cases
2. **t.Run creates subtests** — each case runs independently, can be filtered with `-run`
3. **Uniform structure** — input, expected output, test name
4. **Failures identify which case** — via the case name

### Template

```go
func TestFoo(t *testing.T) {
    tests := []struct {
        name string
        input  InputType
        want   OutputType
        wantErr bool
    }{
        {name: "basic", input: ..., want: ...},
        {name: "empty", input: ..., want: ...},
        {name: "error case", input: ..., wantErr: true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := Foo(tt.input)
            if (err != nil) != tt.wantErr {
                t.Fatalf("Foo() error = %v, wantErr %v", err, tt.wantErr)
            }
            if got != tt.want {
                t.Errorf("Foo() = %v, want %v", got, tt.want)
            }
        })
    }
}
```

### Anti-pattern

```go
// DON'T: Separate test functions for each case
func TestFoo_Basic(t *testing.T) { ... }
func TestFoo_Empty(t *testing.T) { ... }
func TestFoo_Error(t *testing.T) { ... }
// 50 near-identical functions — hard to maintain

// DON'T: Tests without names (hard to identify failures)
tests := []struct{ in, want int }{{1, 2}, {3, 4}}
for _, tt := range tests {
    // which test failed? index 0 or 1?
}
```

---

## 2. t.Helper() — Clean Error Reporting

### Source: `src/testing/testing.go:1415-1435`

```go
// src/testing/testing.go:1415-1435
func (c *common) Helper() {
    if c.isSynctest {
        c = c.parent
    }
    c.mu.Lock()
    defer c.mu.Unlock()
    if c.helperPCs == nil {
        c.helperPCs = make(map[uintptr]struct{})
    }
    var pc [1]uintptr
    n := runtime.Callers(2, pc[:])
    if n == 0 {
        panic("testing: zero callers found")
    }
    if _, found := c.helperPCs[pc[0]]; !found {
        c.helperPCs[pc[0]] = struct{}{}
        c.helperNames = nil
    }
}
```

### Why

When a test helper calls `t.Helper()`, failures report the **caller's** line number, not the helper's. Without it, every failure points to the helper function — useless for identifying which test case failed.

### Idiomatic Usage

```go
func assertNoError(t *testing.T, err error) {
    t.Helper()  // failures point to the caller, not this line
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
}

func assertEqual(t *testing.T, got, want any) {
    t.Helper()
    if !reflect.DeepEqual(got, want) {
        t.Errorf("got %v, want %v", got, want)
    }
}
```

### Anti-pattern

```go
// DON'T: Forget t.Helper() in test helpers
func checkResult(t *testing.T, got, want string) {
    // Missing t.Helper()
    if got != want {
        t.Errorf("got %q, want %q", got, want)
        // Error points HERE, not the actual test case — confusing
    }
}
```

---

## 3. t.Run() — Subtests and Test Organization

### Source: `src/testing/testing.go:2204-2260`

```go
// src/testing/testing.go:2204-2215
func (t *T) Run(name string, f func(t *T)) bool {
    t.hasSub.Store(true)
    testName, ok, _ := t.tstate.match.fullName(&t.common, name)
    if !ok || shouldFailFast() {
        return true
    }
    // ...
    ctx, cancelCtx := context.WithCancel(context.Background())
    t = &T{
        common: common{
            name:   testName,
            parent: &t.common,
            // ...
        },
    }
    go tRunner(t, f)
    // ...
}
```

### Why

Subtests:
1. **Run in separate goroutines** — isolated from each other
2. **Have their own context** — `context.WithCancel(context.Background())`
3. **Can be filtered** — `go test -run TestFoo/subcase`
4. **Can run in parallel** — via `t.Parallel()` inside the subtest
5. **Share setup/teardown** — parent test's defer runs after all subtests

### Pattern: Setup/Teardown with Subtests

```go
func TestDB(t *testing.T) {
    db := setupTestDB(t)  // shared setup
    t.Cleanup(func() { db.Close() })  // runs after ALL subtests

    t.Run("Insert", func(t *testing.T) {
        // uses db
    })
    t.Run("Query", func(t *testing.T) {
        // uses db
    })
}
```

### Anti-pattern

```go
// DON'T: Rely on test execution order
func TestInsert(t *testing.T) { ... }  // must run before TestQuery
func TestQuery(t *testing.T) { ... }   // depends on TestInsert's side effects
// Tests should be independent!
```

---

## 4. t.Parallel() — Concurrent Test Execution

### Source: `src/testing/testing.go:1912`

```go
// src/testing/testing.go:1912
func (t *T) Parallel() {
    // ...marks test as parallel, pauses until parent completes
}
```

### Why

`t.Parallel()` signals that this test can run concurrently with other parallel tests. The test pauses until its parent test function returns, then runs alongside other parallel subtests.

### Idiomatic Usage

```go
func TestFoo(t *testing.T) {
    tests := []struct{
        name string
        input int
    }{
        {"small", 1},
        {"large", 1000},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            t.Parallel()  // runs concurrently with other subtests
            result := expensiveOperation(tt.input)
            if result != expected {
                t.Errorf(...)
            }
        })
    }
}
```

### Anti-pattern

```go
// DON'T: Parallel tests that share mutable state
var counter int
func TestA(t *testing.T) {
    t.Parallel()
    counter++  // DATA RACE
}
func TestB(t *testing.T) {
    t.Parallel()
    counter++  // DATA RACE
}

// DON'T: Capture loop variable in Go < 1.22 without explicit copy
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        t.Parallel()
        // In Go < 1.22: tt is shared — always sees last value
        // In Go >= 1.22: loop variables are per-iteration (fixed)
    })
}
```

---

## 5. t.Cleanup() — Deterministic Teardown

### Source: `src/testing/testing.go:1439`

```go
// src/testing/testing.go:1439-1442
// Cleanup registers a function to be called when the test (or subtest)
// and all its subtests complete. Cleanup functions will be called in
// last added, first called order.
func (c *common) Cleanup(f func()) { ... }
```

### Why

`t.Cleanup` is like `defer` but tied to test lifecycle, not function scope. It runs after all subtests complete and works with parallel tests.

### Idiomatic Usage

```go
func setupTestDB(t *testing.T) *sql.DB {
    t.Helper()
    db, err := sql.Open("sqlite3", ":memory:")
    if err != nil {
        t.Fatal(err)
    }
    t.Cleanup(func() {
        db.Close()
    })
    return db
}

// Caller doesn't need to worry about cleanup:
func TestQueries(t *testing.T) {
    db := setupTestDB(t)  // automatically cleaned up
    // ...
}
```

### Anti-pattern

```go
// DON'T: Return cleanup functions (easy to forget)
func setupDB(t *testing.T) (*sql.DB, func()) {
    db := ...
    return db, func() { db.Close() }
}
// Caller must remember: db, cleanup := setupDB(t); defer cleanup()

// DO: Use t.Cleanup inside the setup function
```

---

## 6. t.TempDir() — Automatic Temp Directories

### Source: `src/testing/testing.go:1575`

```go
// src/testing/testing.go:1575
func (c *common) TempDir() string { ... }
```

### Why

Creates a temp directory that's automatically removed when the test completes. No manual cleanup needed, no leftover test artifacts.

### Idiomatic Usage

```go
func TestWriteConfig(t *testing.T) {
    dir := t.TempDir()  // auto-cleaned
    path := filepath.Join(dir, "config.json")
    
    err := WriteConfig(path, myConfig)
    if err != nil {
        t.Fatal(err)
    }
    
    got, _ := os.ReadFile(path)
    // assert contents...
}
```

### Anti-pattern

```go
// DON'T: Create temp dirs manually and forget cleanup
func TestWrite(t *testing.T) {
    dir, _ := os.MkdirTemp("", "test")
    // forgot os.RemoveAll(dir) — test leaves garbage
}
```

---

## 7. testdata/ Directory

### Source: `src/net/http/testdata/`, `src/encoding/json/testdata/` (implicit — exists in the tree)

```
src/net/http/testdata/
├── file
├── index.html
└── style.css
```

### Why

The `testdata/` directory is special in Go:
1. **Ignored by the go tool** — not compiled as a package
2. **Available to tests** — accessed via relative path `"testdata/file.txt"`
3. **Committed to repo** — test fixtures live alongside the code
4. **Portable** — tests work without external dependencies

### Idiomatic Usage

```go
func TestParse(t *testing.T) {
    input, err := os.ReadFile("testdata/input.json")
    if err != nil {
        t.Fatal(err)
    }
    want, err := os.ReadFile("testdata/expected.json")
    if err != nil {
        t.Fatal(err)
    }
    
    got := Parse(input)
    if !bytes.Equal(got, want) {
        t.Errorf("Parse mismatch")
    }
}
```

### Golden File Pattern

```go
func TestOutput(t *testing.T) {
    got := generateOutput()
    golden := filepath.Join("testdata", t.Name()+".golden")
    
    if *update {  // -update flag to regenerate
        os.WriteFile(golden, got, 0644)
    }
    
    want, _ := os.ReadFile(golden)
    if !bytes.Equal(got, want) {
        t.Errorf("output mismatch; run with -update to regenerate")
    }
}
```

### Anti-pattern

```go
// DON'T: Embed large test fixtures as string literals
var testInput = `{
    "very": "long",
    "json": "string",
    // 500 lines...
}`

// DON'T: Depend on external URLs for test data
func TestParse(t *testing.T) {
    resp, _ := http.Get("https://example.com/test.json")  // flaky!
}
```

---

## 8. Error Message Formatting

### Source: `src/encoding/json/encode_test.go` (throughout)

```go
// Pattern from encode_test.go:304
t.Fatalf("%s: MarshalIndent error: %v", tt.Where, err)

// Pattern from encode_test.go:306-307
t.Fatalf("%s: MarshalIndent:\n\tgot:  %s\n\twant: %s", tt.Where, got, want)

// Pattern from encode_test.go:421-422
t.Errorf("%s: Marshal error:\n\tgot:  %T\n\twant: %T", tt.Where, err, new(UnsupportedValueError))
```

### Why

The stdlib follows a consistent error format:
- **Context first** — where/what was being tested
- **got/want on separate lines** — easy to diff visually
- **Tab-indented** — aligns the comparison

### Convention

```
t.Errorf("FunctionName(%v) = %v, want %v", input, got, want)
// or for complex values:
t.Errorf("FunctionName(%v):\n\tgot:  %v\n\twant: %v", input, got, want)
```

### Anti-pattern

```go
// DON'T: Vague error messages
t.Error("failed")  // what failed? what was expected?

// DON'T: Only show the got value
t.Errorf("got %v", got)  // what was expected?

// DON'T: Use assert libraries that hide the actual comparison
assert.Equal(t, got, want)  // when it fails: "not equal" — which is which?
```

---

## 9. t.Fatal vs t.Error

### Convention across stdlib

```go
// Fatal: test cannot continue meaningfully
db, err := sql.Open("sqlite3", ":memory:")
if err != nil {
    t.Fatal(err)  // no point continuing without a database
}

// Error: test can continue, report all failures
for _, tt := range tests {
    got := fn(tt.input)
    if got != tt.want {
        t.Errorf(...)  // report and keep going
    }
}
```

### Why

- `t.Fatal` / `t.Fatalf` — **stops the test immediately**. Use for setup failures where subsequent assertions are meaningless.
- `t.Error` / `t.Errorf` — **reports failure, continues**. Use in loops to collect all failures at once.

### Anti-pattern

```go
// DON'T: Fatal in loops (misses subsequent failures)
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        if got != tt.want {
            t.Fatalf(...)  // stops this subtest — fine in subtests actually
        }
    })
}
// But without subtests:
for _, tt := range tests {
    if got != tt.want {
        t.Fatalf(...)  // stops ALL remaining cases!
    }
}

// DON'T: Error when you can't continue
file, err := os.Open(path)
if err != nil {
    t.Errorf("open: %v", err)  // continues to use nil file — panic!
}
file.Read(...)
```

---

## 10. Test Naming Conventions

### Source: All stdlib tests follow these patterns

```go
// Function tests: TestFunctionName
func TestMarshal(t *testing.T) { ... }

// Method tests: TestTypeName_MethodName
func TestEncoder_Encode(t *testing.T) { ... }

// Behavior tests: TestDescription
func TestOmitEmpty(t *testing.T) { ... }

// Edge cases: TestFunctionName_EdgeCase
func TestMarshal_NilSlice(t *testing.T) { ... }

// Benchmarks: BenchmarkFunctionName
func BenchmarkMarshal(b *testing.B) { ... }

// Examples: ExampleFunctionName
func ExampleMarshal() {
    // ...
    // Output: {"name":"Alice"}
}
```

### Why

- Test names are used with `-run` flag for filtering
- They appear in failure output — should be self-explanatory
- Example functions become documentation (shown in godoc)
- Subtests use `/` separator: `TestMarshal/NilSlice`

### Anti-pattern

```go
// DON'T: Numbered tests
func Test1(t *testing.T) { ... }
func Test2(t *testing.T) { ... }

// DON'T: Tests that don't start with Test
func testHelper(t *testing.T) { ... }  // won't be run! (lowercase 't')

// DON'T: Overly verbose names
func TestThatMarshalCorrectlyHandlesNilSliceInputAndReturnsNullJSON(t *testing.T) { ... }
```

---

## Summary: Testing Best Practices

| Pattern | When |
|---------|------|
| Table-driven tests | Multiple inputs for same logic |
| t.Run subtests | Isolate cases, enable `-run` filtering |
| t.Helper() | Every test helper function |
| t.Parallel() | Independent tests, speed up suite |
| t.Cleanup() | Resource teardown (replaces defer in helpers) |
| t.TempDir() | Need filesystem for test |
| testdata/ | External test fixtures |
| Golden files | Complex expected output |
| t.Fatal | Setup failures (can't continue) |
| t.Error | Assertion failures (collect all) |
| got/want format | `"got %v, want %v"` or `"\n\tgot:  %v\n\twant: %v"` |