Go Testing (go test)

Guides agents through executing, isolating, and debugging Go test suites. Enforces canonical table-driven test patterns, subtests (t.Run), and data race detection (-race).

1. Purpose

Execute and debug Go tests. A "Table-Driven Test" iterates over a slice of test case structs containing name, inputs, and expected outcomes.

2. When to Use

Use this skill when:

• Running tests in Go projects (go test ./...).
• Running a single targeted Go test using -run.
• Checking for concurrent race conditions using go test -race.

3. When Not to Use

• Do not use for Python or TS tests; use py-testing or ts-testing.
• Do not use for static linting; use go-lint-and-vet.

4. Required Inputs

• package_path: Go package path (e.g. ./internal/auth or ./...).
• test_name: Optional regex pattern for -run.

5. Missing-Input Behavior

1. If package_path is missing: default to ./....
2. Never write empty test functions without assertions.

6. Procedure

Follow these numbered actions:

1. Action 1: Run Targeted Test
   • Execute: go test -v -run "^<test_name>$" <package_path>
2. Action 2: Check for Concurrency Data Races
   • Execute: go test -race <package_path>
3. Action 3: Trace Assertion Failure
   • Look for t.Errorf("got %v, want %v", got, want) outputs.
4. Action 4: Apply Fix & Verify
   • Re-run test until PASS.
5. Action 5: Run Entire Package Suite
   • Execute go test ./....

7. Decision Rules

• If concurrency is tested: always pass -race flag.
• When writing table tests: use for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { ... }) }.

8. Output Format

Emit the report using this template:

### Go Test Report: [Package]

- **Command**: `go test -v -run "[pattern]" [package]`
- **Status**: [PASS | FAIL]
- **Race Check**: [PASS | DETECTED]

#### Results
- [Summary of passed/failed tests]

9. Verification Checklist

• go test executed with clean PASS.
• go test -race passes with zero data races.
• Tests follow table-driven structure.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Tests require external CGO bindings or proprietary database connections.

12. Examples

Example 1: Successful Execution

Input:

Package: ./pkg/math
Test: TestAdd

Output:

### Go Test Report: ./pkg/math

- **Command**: `go test -v -run "^TestAdd$" ./pkg/math`
- **Status**: PASS
- **Race Check**: PASS

#### Results
- `=== RUN   TestAdd`
- `--- PASS: TestAdd (0.00s)`

Example 2: Ambiguous or Missing Input

Input:

Test go.

Output:

### Go Test Report: Halted - Ambiguous Package

- **Status**: Halted

Please specify the Go package to test (e.g. `./cmd/...` or `./internal/auth`).

Example 3: Expected Final Output

Output:

### Go Test Report: ./internal/cache

- **Command**: `go test -race ./internal/cache`
- **Status**: PASS
- **Race Check**: PASS