golden-file-conventions

Terminology note: "golden file" / "golden master" are practitioner-emergent terms popularized by the Working Effectively with Legacy Code tradition. ISTQB has no canonical entry - the closest formal term is "snapshot test." This catalog uses both interchangeably; assume "golden file" and "snapshot" mean the same thing in the rest of the body.

A reference catalog for how to manage snapshot / golden files. Pairs with golden-file-manager which is the active management agent that updates / prunes golden files based on these conventions.

When to use

• A team is starting snapshot-testing on a project.
• A team has an existing snapshot suite and reviews are slow because of unclear conventions.
• A developer is unsure when to update a baseline vs. when to fix the regression.
• A PR review keeps stalling on "is this snapshot diff intentional?"

Naming conventions

Per-test snapshot file

Most snapshot frameworks (Jest, Vitest, pytest-snapshot, RSpec Snapshot) use a path adjacent to the test file:

src/
  components/
    Button.tsx
    Button.test.tsx
    __snapshots__/
      Button.test.tsx.snap

Convention: one snapshot file per test file, named <test-file-name>.snap. Do not split snapshots across multiple files per test.

Per-test name within a snapshot file

Inside a .snap file, each snapshot is keyed by <describe> > <it> chain:

exports[`Button renders with primary variant 1`] = `<button class="primary">...</button>`;

The trailing 1 is the snapshot index when one test takes multiple snapshots - keep these to a minimum (≤3 per test); beyond that, split the test.

Per-OS / per-browser variants (visual snapshots)

For visual / screenshot-based snapshots, the name carries the platform suffix (per playwright-snapshots):

Button-primary-1-chromium-linux.png
Button-primary-1-firefox-linux.png
Button-primary-1-webkit-darwin.png

OS / browser suffixes are load-bearing - anti-aliasing and font metrics differ. Don't strip them.

Directory layout

Default to adjacent. Centralized only when fixtures are reused. External only when artifact size makes adjacent impractical.

When to add a baseline

Add a snapshot when:

• A new component / page / output ships and its rendered shape is load-bearing.
• A bug fix changes a specific output that lacked coverage; the snapshot is the regression-prevention asset.
• A redesign locked the new design system; refresh all baselines in one PR.

Don't add a snapshot for:

• Output that's expected to change frequently (e.g. timestamps, randomized IDs). Snapshot the shape, not the volatile values - see Sanitization below.
• Internal-only rendering paths the user never sees.
• Test scaffolding output (e.g. test runner banners).

Sanitization (the load-bearing rule)

A snapshot that contains volatile values (timestamps, UUIDs, random IDs, current dates) breaks every run. Sanitize before snapshotting:

Most frameworks support custom serializers / matchers - use them. Jest's expect.any(Date) matcher pattern is canonical:

expect(result).toMatchSnapshot({
  createdAt: expect.any(Date),
  uuid: expect.any(String),
});

The serializer normalizes volatile fields before comparison, so the snapshot shows Any<Date> rather than a specific timestamp.

Update vs. fix decision tree

When a snapshot diff appears in a PR:

Is the diff explained by code changes in the same PR?
├── No  → REGRESSION; fix the code, do not update the snapshot.
└── Yes → Did the diff align with the intent (described in the PR title)?
    ├── No  → REGRESSION (cascade from an unrelated change); investigate before updating.
    └── Yes → Is the diff isolated to the components the PR is supposed to change?
        ├── No  → INVESTIGATE: a CSS / token / shared-component change affected unrelated snapshots.
        └── Yes → UPDATE: run `--update-snapshots` and commit.

The most common review failure is rubber-stamping snapshot updates - accepting a 47-component diff because the PR title says "Refactor Button". The diff classifier in golden-file-manager implements this decision tree.

Severity tiering

Every snapshot has an implicit severity:

Promote Advisory → Standard after ~2 weeks of stability. Promote Standard → Critical for security-sensitive surfaces.

Pruning rules

Remove a snapshot when:

• The associated test is deleted.
• The component / page is removed from the product.
• The snapshot has produced more false positives than real regressions over a 3-month window - it's noise, not signal.

The golden-file-manager agent automates the "test deleted but snapshot remained" cleanup.

Anti-patterns

Review workflow

1. PR opens with snapshot diff. Reviewer reads the PR title / description first to understand intent.
2. Reviewer checks each diff cell against the decision tree above.
3. For unintended diffs: comment with the specific cell + ask for code investigation; do not approve.
4. For intended diffs: approve; the snapshot becomes the new baseline.
5. For ambiguous diffs: request a second reviewer; treat as Critical-tier even if labeled Standard.

References

• ISO/IEC/IEEE 29119 series - formal test-document conventions (cite by stable ID).
• golden-file-manager - active-management agent that uses this catalog.
• playwright-snapshots - visual-snapshot-specific naming and per-OS suffix conventions.
• visual-baseline-conventions - broader visual-coverage conventions; this skill is the text/object-snapshot equivalent.