1.2.9 Golden File Testing (Test-Accept Pattern)

Golden-file testing keeps an expected output under version control and asks a normal Bazel test to compare today's generated output against that checked-in baseline^1,2. The clean operator split is simple: bazel test verifies, while a separate .accept target run with bazel run updates the golden when the change is intentional¹. That keeps the default test path read-only, reviewable, and safe to leave in ordinary test sweeps.

What The Golden Protects

A Bazel test checks source files in the repository, including test data and golden outputs². A golden file is part of the repository state the test is asserting about.

The usual hermeticity discipline still applies. The test should depend only on declared source files, declared build outputs, and runner-provided stable resources². If the produced output depends on timestamps, random ordering, network state, or other undeclared inputs, the test produces repeated, irrelevant churn instead of useful signal. This is the same pressure toward 2.3 Hermeticity & Sandboxing, applied to checked-in expected output.

Two Targets, Two Jobs

A good Bazel golden workflow has two labels with different responsibilities. The test target compares actual versus expected and is the thing you keep in ordinary bazel test sweeps. The accept target performs the intentional side effect of rewriting the checked-in golden when the diff is correct¹.

At the low level, the standard verification shape is straightforward: a *_test target receives the artifact it should inspect through data and args³. The operator-facing extension is that the same script or macro can expose a paired runnable target, often named .accept, that switches from "verify" to "update" mode. The project exposes this update path as an executable target launched with bazel run. Bazel has no native bazel test-accept command¹. If you need the runtime details of that side-effect path, they are the same ones covered in 1.1.2 bazel run & Runfiles.

A Minimal Bazel Shape

In practice the BUILD file is usually small. The compare step uses the ordinary data-flow mechanics from 0.3.3 Attributes & Semantic Roles: produce an output, pass it to a test, and also pass the checked-in golden.

load("@rules_shell//shell:sh_binary.bzl", "sh_binary")
load("@rules_shell//shell:sh_test.bzl", "sh_test")

genrule(
    name = "actual_report",
    srcs = ["source.txt"],
    outs = ["actual_report.txt"],
    cmd = "tr '[:lower:]' '[:upper:]' < $(location source.txt) > $@",
)

sh_test(
    name = "report_test",
    srcs = ["verify.sh"],
    size = "small",
    args = ["$(location :actual_report.txt)", "$(location golden.txt)"],
    data = [":actual_report.txt", "golden.txt"],
)

sh_binary(
    name = "report.accept",
    srcs = ["accept.sh"],
    args = ["$(rlocationpath :actual_report.txt)", "golden.txt"],
    data = [":actual_report.txt"],
    deps = ["@bazel_tools//tools/bash/runfiles"],
)

The golden-file-accept snippet in this repository uses exactly that shape. report_test compares a generated text file to golden.txt, while report.accept resolves the generated file from runfiles and updates the checked-in golden only when it drifted.

Where This Pattern Fits

The pattern is strongest when the output is stable, reviewable text. Angular's ts_api_guardian_test uses it for API surface checks, and ruleset documentation pipelines use the same idea to keep checked-in generated docs synchronized with current output^1,4.

The pattern is weak when the output is naturally noisy. If the generated file includes nondeterministic ordering, timestamps, machine-specific paths, or other ambient state, the golden diff does not tell reviewers "the behavior changed" so much as "the environment leaked into the result"². In those cases, fix the determinism first or choose a different assertion shape.