Go test suite reported one or more test failures

What this failure means

One or more Go test functions failed or panicked. The go test runner reported the failure with --- FAIL: for individual tests and FAIL for the package summary.

Symptoms

Faultline looks for one or more of these log fragments:

--- FAIL:
FAIL: Test
FAIL github.com/
Test (
TestIntegration
TestBootstrap
#coordinator
#datastore

Diagnosis

The Go test runner (go test) terminated with a non-zero exit code. Individual failing test functions are reported as:

--- FAIL: TestSomething (0.01s)
    foo_test.go:42: expected 5 but got 7
FAIL    github.com/example/repo/pkg    0.042s

Common causes:

• Assertion failure — a test assertion (t.Fatal, t.Error, require, assert) did not hold; the application behaviour changed.
• Panic in test — the code under test or the test itself panicked; Go reports this as a test failure with a goroutine stack trace.
• Test timeout — the test exceeded the context deadline or the suite timeout (go test -timeout); the runner forcibly terminates and reports panic: test timed out after Xs.
• Race condition — the race detector (-race) flagged unsynchronised memory access.
• Data-dependent failure — the test depends on external state (database, network, filesystem) that is absent or different in CI.
• Build failure inside test — the test package failed to compile; the output includes a build failed summary.

Fix steps

1. Reproduce the failing tests locally:

   go test ./...
   go test -v ./path/to/failing/package
   

2. For a specific failing test:

   go test -run TestFunctionName ./path/to/package
   

3. Read the full --- FAIL: block — it shows the file, line number, and the assertion that failed.

4. For panics, read the goroutine stack trace to find the call site.

5. For timeouts, increase the timeout or investigate why the test hangs:

   go test -timeout 120s ./...
   go test -v -timeout 60s ./path/to/package 2>&1 | grep -A5 "timed out"
   

6. For a build failure, run go build ./... to see the compiler errors in isolation, then fix the compilation errors before re-running tests.

Validation

• go test ./... exits zero.
• go test -race ./... exits zero for race-sensitive packages.
• Individual test: go test -run TestFunctionName ./pkg exits zero.

Why it matters

Go test failures are deterministic. The --- FAIL: block names the exact test function, file, and line. Even a single failing test blocks the pipeline because go test returns a non-zero exit code when any assertion fails — downstream steps that depend on a passing test result will not run.

Prevention

• Run go test ./... as a pre-push hook.
• Add -race to CI test runs to detect data races before they reach production.
• Use t.Parallel() on independent tests to surface race conditions early.
• Keep tests hermetic: avoid shared global state and external dependencies.

Try it locally

go test ./...
go test -v ./path/to/failing/package
go test -run TestFunctionName ./path/to/package
go test ./...

How Faultline detects it

Use faultline explain go-test-failure to see the full playbook.

faultline analyze build.log
faultline explain go-test-failure

Generated from playbooks/bundled/log/test/go-test-failure.yaml. Do not edit directly.