Go "--- FAIL:" Test Failures - Read and Fix in CI

By Kaveh Alemi·Latchkey

A test reported a failure. Go prints --- FAIL: TestName for each failing test (and --- FAIL: TestName/subtest for table-driven subtests), with the t.Error/t.Fatal message that explains what assertion did not hold.

What this error means

A go test run prints one or more --- FAIL: lines with the failing test (and subtest) names and their messages, ending in FAIL <package>. The failure is in your code or the test’s expectations, and it reproduces with the same inputs.

go test output

--- FAIL: TestParse (0.00s)
    --- FAIL: TestParse/empty_input (0.00s)
        parse_test.go:41: got error nil, want ErrEmpty
FAIL
FAIL	github.com/org/app/internal/parse	0.012s

Common causes

A genuine assertion failure

The code under test produced a result the test did not expect - a real behavior bug or an out-of-date expectation after an intended change.

A wrong or stale expected value

The test asserts an expectation that no longer matches intended behavior, so the assertion fails even though the code is correct.

Environment-dependent assertions

A test that depends on time zone, ordering, or locale can fail in CI where those differ from a developer machine.

How to fix it

Reproduce the exact failing (sub)test

Run just the failing test with verbose output to see the assertion and values.

Terminal

go test -v -run 'TestParse/empty_input' ./internal/parse

Fix the code or the expectation

Read the t.Error/t.Fatal message - it states got vs want.
If the code is wrong, fix it; if the behavior changed intentionally, update the expectation.
Make environment-sensitive tests deterministic (inject time, sort before comparing).

How to prevent it

Write deterministic tests - inject time, fix ordering, pin locale.
Use table-driven subtests so failures name the exact case.
Run go test ./... locally before pushing.

Frequently asked questions

What causes ""--- FAIL: TestName""?