Golden files and testdata
A golden file is the expected output of a function, stored in the repository and compared byte for byte. It is the practical way to test a formatter, a template, a JSON encoder or a command's help text, where the expectation is a page rather than a value. The convention is a testdata directory, which the Go toolchain ignores when it builds packages, so the file travels with the test and never with the binary. The handler lesson compared bodies with strings; a golden file is the same idea with the body in a file.
The function under test
The formatter writes a table with text/tabwriter and returns a string, which makes it testable without a terminal. The rows are in a slice, so the output is deterministic: a map would iterate in a random order and the golden file would fail every other run, which is the first question to ask before adopting this technique.
package report
import (
"flag"
"os"
"path/filepath"
"testing"
)
var update = flag.Bool("update", false, "rewrite the golden files")
func TestRender(t *testing.T) {
rows := []Row{{"ada", 91}, {"grace", 88}}
got, err := Render(rows)
if err != nil {
t.Fatal(err)
}
path := filepath.Join("testdata", "report.golden")
if *update {
if err := os.MkdirAll("testdata", 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
t.Fatal(err)
}
return
}
want, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read golden: %v (run go test -update)", err)
}
if got != string(want) {
t.Errorf("output changed:\n--- want\n%s\n--- got\n%s", want, got)
}
}
go test -v .
=== RUN TestRender
--- PASS: TestRender (0.00s)
PASS
ok example.com/report 0.006s
The test read the file and compared the string, and the golden content is exactly what the formatter produced:
cat testdata/report.golden
name score
ada 91
grace 88
The columns line up because the golden captured the tabwriter output, spaces and all. A golden file tests the formatting as well as the text, which a comparison of parsed values would not: a table that loses a space is a regression for the reader even when every number is right.
Rewriting the golden on purpose
go test -update makes the test write the current output over the golden instead of failing. The flag is defined in the test file with flag.Bool, and the test returns right after writing, so an update run cannot also fail on the old content. The rewritten file then goes into the same review as the code that changed it, which is the whole discipline: the golden is not a scratch file.
package report
import (
"flag"
"os"
"path/filepath"
"testing"
)
var update = flag.Bool("update", false, "rewrite the golden files")
func TestRender(t *testing.T) {
rows := []Row{{"ada", 91}, {"grace", 88}}
got, err := Render(rows)
if err != nil {
t.Fatal(err)
}
path := filepath.Join("testdata", "report.golden")
if *update {
if err := os.MkdirAll("testdata", 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
t.Fatal(err)
}
return
}
want, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read golden: %v (run go test -update)", err)
}
if got != string(want) {
t.Errorf("output changed:\n--- want\n%s\n--- got\n%s", want, got)
}
}
go test -v -update .
=== RUN TestRender
--- PASS: TestRender (0.00s)
PASS
ok example.com/report 0.004s
The update run passed and the file now holds the formatter's output. A test that always runs with -update proves nothing, so the flag belongs to a developer's command line and never to CI; a CI job runs the plain go test and fails when the output moved.
What a mismatch prints
A failing golden test shows the expected and the actual text, which is enough to see whether the change is a fix or a regression. The message is the test author's to write: printing both sides with a separator is the minimum, and a diff library makes a long file readable. The important part is that the failure names the feature and not just a line number.
A golden file is right when the output is stable and readable by a human. It is wrong when the output contains timestamps, absolute paths, map order or random ids: those have to be normalised before the comparison, or the test teaches the team to run -update without reading, which is worse than having no test.
Exercises
- Add a row to the report and run the test without -update. Copy the failure message and decide whether the change is expected.
- Add a name column with a long value and see how the tabwriter changes the widths. Which part of the golden file moved?
- Write a golden test for a command that prints a help text, and normalise the program name before the comparison. What else in that output could vary between machines?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Where does a golden file usually live?
Answer
In a testdata directory next to the test
testdata is ignored by the build, so the file is available to tests and absent from the binary.
-
What does the -update flag do?
Answer
Rewrites the golden file with the current output
The flag is defined by the test and turns the run into a file write.
-
Why must a golden test avoid map iteration?
Answer
The order is random, so the output changes every run
A golden file requires deterministic output.
-
What does a failing golden test print?
Answer
The expected and the actual text
Both sides are printed so a reader can tell a fix from a regression.
-
Who should run go test -update?
Answer
A developer, who then reviews and commits the new file
An automatic update proves only that the code still runs.
-
Which output is a bad fit for a golden file?
Answer
A report with a timestamp on every line
Volatile data has to be normalised or the test fails for irrelevant reasons.
-
How can a golden file be kept out of the built package?
Answer
By putting it under testdata, which the build ignores
The directory name is the convention the toolchain understands.
-
What does a golden file test compared with comparing parsed values?
Answer
It also tests the exact formatting, spaces included
The byte-for-byte comparison covers layout, which parsed comparison loses.
-
Why is the update run a single command?
Answer
Because the test writes the file and returns without comparing
Writing and comparing in one run would compare the file with itself.
-
What should the failure message contain?
Answer
The feature name and both versions of the text
A reader must be able to tell what changed and whether it was intended.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev