Golden files and testdata
A golden file is the expected output of a function, kept as a file next to the test and compared as text. It is the right shape for a report, a formatted document, a JSON document with forty fields or the help of a command line tool: the test says nothing about the content, and the file is the content. Go gives the convention and one detail for free, the testdata directory, and the rest is a flag of the test binary.
A report and its golden file
The package formats rows into fixed-width columns, sorted by name, which is the kind of output a person reads in a terminal and a golden file holds well. The folder has three parts:
report/
report.go
report_test.go
testdata/
report.golden
The go tool ignores a directory named testdata: it is not compiled, not vetted and not listed by ./..., so a file there is data for a test and nothing else.
package report
import (
"fmt"
"io"
"sort"
)
// Row is one line of the report.
type Row struct {
Name string
Count int
}
// Write writes the report for rows, sorted by name.
func Write(w io.Writer, rows []Row) error {
sort.Slice(rows, func(i, j int) bool { return rows[i].Name < rows[j].Name })
for _, r := range rows {
if _, err := fmt.Fprintf(w, "%-10s %3d\n", r.Name, r.Count); err != nil {
return err
}
}
return nil
}
The test writes the report into a bytes.Buffer and compares it with the file. The -update flag is declared with flag.Bool and therefore appears on the test binary without another line of code, because go test passes unknown flags to the binary it built.
package report
import (
"bytes"
"flag"
"fmt"
"os"
"path/filepath"
"strings"
"testing"
)
var update = flag.Bool("update", false, "rewrite the golden files")
func TestReport(t *testing.T) {
var buf bytes.Buffer
rows := []Row{{"api", 3}, {"jobs", 12}, {"web", 0}}
if err := Write(&buf, rows); err != nil {
t.Fatal(err)
}
golden := filepath.Join("testdata", "report.golden")
if *update {
if err := os.WriteFile(golden, buf.Bytes(), 0o644); err != nil {
t.Fatal(err)
}
}
want, err := os.ReadFile(golden)
if err != nil {
t.Fatalf("%v: run go test -update to write it", err)
}
if got := buf.String(); got != string(want) {
t.Errorf("report differs from %s:\n%s", golden, firstDiff(string(want), got))
}
}
// firstDiff returns the first line where want and got differ.
func firstDiff(want, got string) string {
w, g := strings.Split(want, "\n"), strings.Split(got, "\n")
for i := 0; i < len(w) || i < len(g); i++ {
var a, b string
if i < len(w) {
a = w[i]
}
if i < len(g) {
b = g[i]
}
if a != b {
return fmt.Sprintf("line %d:\n want %q\n got %q", i+1, a, b)
}
}
return ""
}
The first run
On a fresh checkout the file does not exist, and the test says what to do instead of failing with a path:
go test -v -run TestReport ./report
=== RUN TestReport
report_test.go:30: open testdata/report.golden: no such file or directory: run go test -update to write it
--- FAIL: TestReport (0.00s)
FAIL
FAIL example.com/reports/report 0.004s
FAIL
The message is the contract of the flag: a reader who has never seen the package knows the next command. Without the sentence the same failure would read as a missing file and send the reader looking for a broken build.
The -update flag
-update writes the file from the current output and then lets the test compare, so a run that writes also checks. That second part matters: a flag that writes and skips the comparison turns every golden test into a test that cannot fail.
go test -run TestReport -update ./report
PASS
ok example.com/reports/report 0.004s
The file that was written, with a space kept on purpose so the columns line up:
cat report/testdata/report.golden
api 3
jobs 12
web 0
A second run reads it and passes:
go test -v -run TestReport ./report
=== RUN TestReport
--- PASS: TestReport (0.00s)
PASS
ok example.com/reports/report 0.004s
A stale golden file
The common failure is a file that no longer matches the code: someone changed the format and did not run the update, or edited the golden file by hand. Here the second line of the file was changed to a wrong number, and the test reports the first line where the two texts differ:
sed -i 's/jobs 12/jobs 13/' report/testdata/report.golden
go test -v -run TestReport ./report
=== RUN TestReport
report_test.go:33: report differs from testdata/report.golden:
line 2:
want "jobs 13"
got "jobs 12"
--- FAIL: TestReport (0.00s)
FAIL
FAIL example.com/reports/report 0.006s
FAIL
Both strings are printed with %q, so a trailing space or a tab is visible instead of being lost in the terminal. The first difference is enough for a three-line report; for a hundred-line document a test prints the whole diff, which is what cmp.Diff does on the assertions page. The update puts the file back:
go test -run TestReport -update ./report
cat report/testdata/report.golden
PASS
ok example.com/reports/report 0.004s
api 3
jobs 12
web 0
What belongs in a golden file
A golden file is a promise about text, so the text must be stable. A timestamp, a temporary path, a port number or the order of a map makes the file different on every run, and the test then fails for a reason that has nothing to do with the code. Print those values through a function the test replaces, or keep them out of the compared text.
A change to a golden file is a change to the expected output, so it belongs in the same review as the code that caused it. That is the weakness of the approach: a reviewer who only sees go test -update and a large diff has no way to tell a fixed bug from a broken report. The smaller the file, the better the review; one file per case under testdata/report/ keeps each diff readable.
The lesson on golden files and testdata builds the same pattern for a template, and the JSON capstone uses it for the formatted output in table tests and fuzzing.
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