Golden File Testing

In Plain Words

Say a function emits 300 lines of generated code, a long error message or a JSON payload a partner parses byte for byte. Writing an assertion for every line is miserable, and checking only a few lines lets the rest drift. A golden file is the shortcut: save the whole output once, look at it, agree that it is right, and from then on make the test compare against that saved copy.

The vocabulary is small. The golden file is the stored expected output, often named with a .golden extension. In Go projects it sits in a testdata directory, which the go tool ignores and ./... patterns skip. The update flag is a switch you pass to the test run that tells it to overwrite the golden files with whatever the code produces now, instead of comparing. No spec or single tool owns the term, so each ecosystem names the files and the flag its own way.

"Golden" means accepted, not proven. The file records what the code did on the day someone approved it, so a bug present in that output is locked in along with everything else.

How It Works

1. The test runs the code and captures its output as got.
2. It reads the golden file from disk as want.
3. Any difference fails the test, ideally printing both versions or a diff.
4. When a change is intended, you rerun with the update flag. The test writes the new output over the golden file and passes.
5. You review the golden file's diff and commit it with the code change.

Here is the Go version, which we ran on Go 1.27.3. The flag is not built into go test; each test package declares it, the same way the standard library's own go/printer tests do with flag.Bool("update", false, "update golden files").

var update = flag.Bool("update", false, "rewrite golden files")

func TestRender(t *testing.T) {
	got := Render("Ada", []string{"tea", "biscuits"})
	path := filepath.Join("testdata", "render.golden")
	if *update {
		os.WriteFile(path, []byte(got), 0o644)
	}
	want, err := os.ReadFile(path)
	if err != nil {
		t.Fatal(err)
	}
	if got != string(want) {
		t.Errorf("Render mismatch\ngot:\n%s\nwant:\n%s", got, want)
	}
}

The first run fails, because nothing has been recorded yet: open testdata/render.golden: no such file or directory. Running go test ./greet -update writes the file. Every later run passes until the output changes. When we changed the greeting from "Hello" to "Hi", the test failed with Render mismatch, printing the new output (Hi, Ada!) above the golden one (Hello, Ada!). Running -update again then rewrote the golden file without a word of complaint, because the flag writes whatever the code produced. That is why the tools agree on the review step: gotest.tools says to compare the diff of the old expected value to the new one, TensorFlow Federated says the resulting diff should be checked for unanticipated changes, and Jest says snapshot files should be committed and reviewed as part of code review.

One trap shows up in any module where some package does not declare the flag. go test ./... -update fails in every package that does not declare the flag, with flag provided but not defined: -update. Run the update against the specific package instead.

The pattern is the same outside Go; only the command differs. The golden file can also be an image: Flutter's matchesGoldenFile compares a widget's rendered image with a stored golden image file.

Why It Matters

Golden files earn their place where the exact bytes are the contract. Go uses them heavily for that reason: the Go 1.27.3 source tree ships 134 .golden files, including the ones that pin gofmt's formatting. The TensorFlow Federated docs name the same territory: error messages, diagnostics and generated code.

Migrations are the other big case. When we wrote the guide to migrating Go encoding/json to v2, Step 2 recorded the current bytes with golden tests while the code was still on v1. One of them caught a difference that survives even with DefaultOptionsV1: v1's Encoder.Encode ends its output with a newline, and v2's MarshalWrite does not. Only a check on the exact bytes sees that. The same tests would flag v2's unsorted map keys, the change our JSON v2 vs v1 write-up warns will break golden-file tests. Pinning output this way is also the cheap safety check before you swap one Go JSON library for another.

The cost is that a golden test checks everything, including things nobody meant to promise. Output that varies between runs makes it flaky: in that migration, -count=20 failed only sometimes, because random map order only sometimes disagreed with the sorted golden file, and json.Deterministic(true) made the output stable again. Flutter's docs warn that custom fonts can render differently across platforms and Flutter versions. TensorFlow Federated's docs go further: golden tests promise exact outputs rather than documented properties, so a well-factored unit test is usually preferable.

Common Confusions