goldenguard

Documentation

Overview

Package goldenguard centralizes the policy that gates EVERY golden-fixture rewrite path in the gitmap test suite.

Why this exists: each golden test has a "regenerate" mode triggered by either an env var (GITMAP_UPDATE_GOLDEN=1) or a -update test flag. Both are easy to flip on accidentally — by a CI matrix that inherits a developer's shell env, a stray flag in a Makefile, or a typo in a `go test` invocation. A silent regenerate is the worst kind of failure because it makes the very test that should catch drift WRITE the drifted bytes to disk and pass.

The fix is a defense-in-depth gate: a regenerate happens ONLY when the per-test trigger AND a dedicated allow-env-var are BOTH set. CI must never set the allow-env-var; humans set it explicitly when they intend to rewrite fixtures. If the trigger is on but the allow var is off, AllowUpdate fails the test with a clear remediation message so the CI failure points straight at the misconfiguration.

Usage from any golden test:

if goldenguard.AllowUpdate(t, *updateFlag) {
    os.WriteFile(path, got, 0o644)
    return
}

Index

• Constants
• func AllowUpdate(t *testing.T, trigger bool) bool
• func AllowUpdateAfterDeterminism(t *testing.T, trigger bool, label string, writer WriterFn) bool
• func AssertWriterDeterministic(t *testing.T, label string, writer WriterFn)
• type WriterFn

Constants

const AllowUpdateEnv = "GITMAP_ALLOW_GOLDEN_UPDATE"

AllowUpdateEnv is the dedicated env var that must be set to "1" to permit ANY golden fixture rewrite, regardless of the per-test trigger (env var or -update flag). Centralized so CI configs and docs reference a single name. Do NOT add a second name — the whole point is that there's exactly one switch CI can pin OFF.

Functions

func AllowUpdate

func AllowUpdate(t *testing.T, trigger bool) bool

AllowUpdate reports whether the caller may rewrite golden fixtures. Returns true ONLY when the per-test trigger is on AND the dedicated allow-env-var is set to "1". When the trigger is on but the allow var is off, the test fails loudly via t.Fatalf — silent skipping would let CI green-light a misconfigured regenerate attempt.

trigger: the per-test signal (e.g. *flag.Bool("update") for the cmd package, os.Getenv("GITMAP_UPDATE_GOLDEN")=="1" for the formatter package). Caller computes it.

func AllowUpdateAfterDeterminism

func AllowUpdateAfterDeterminism(t *testing.T, trigger bool, label string, writer WriterFn) bool

AllowUpdateAfterDeterminism bundles AssertWriterDeterministic with AllowUpdate. When trigger is false this is a fast no-op (returns false without invoking the writer at all) so non-update runs incur zero cost. When trigger is true, the writer must survive determinism BEFORE the gate is consulted — a flaky writer cannot regenerate fixtures, period.

func AssertWriterDeterministic

func AssertWriterDeterministic(t *testing.T, label string, writer WriterFn)

AssertWriterDeterministic runs writer determinismRunCount times and t.Fatalf's if any pair of runs produces different bytes. label is included in failure messages so a test asserting on multiple writers can pinpoint which one drifted.

Types

type WriterFn

type WriterFn func() ([]byte, error)

WriterFn is the contract for a golden writer: it receives no args (the caller closes over inputs) and returns the bytes that would be written to the fixture on disk. Returning an error fails the determinism check immediately — a writer that errors out cannot also be deterministic.