Test Snapshots and Golden Files for Code Agents

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Snapshots and golden files help agents detect output drift, but updating them safely requires understanding why the expected output changed.

## Core Explanation

Snapshot tests compare current output with stored expectations. They are useful for rendered UI, accessibility structures, API payloads, generated code, compiler output, and other data that is easier to review as a stable artifact than as hand-written assertions.

Useful evidence includes snapshot file path, test name, diff, serializer, update command, changed output type, deterministic inputs, environment metadata, and whether the product behavior intentionally changed. A snapshot failure is not automatically a bug; a snapshot update is not automatically safe.

Agents should treat snapshot updates like reviewable product changes. They should explain the semantic difference, avoid bulk updates without a reason, and run targeted tests after changing golden files.

## Source-Mapped Facts

- Playwright documentation describes snapshot testing for comparing text or binary data against expected snapshots. ([source](https://playwright.dev/docs/test-snapshots))
- Playwright documentation describes ARIA snapshots for testing page accessibility structure. ([source](https://playwright.dev/docs/aria-snapshots))
- Vitest documentation describes snapshot tests that compare output to a stored reference snapshot. ([source](https://main.vitest.dev/guide/snapshot))

## Further Reading

- [Playwright Test Snapshots](https://playwright.dev/docs/test-snapshots)
- [Playwright ARIA Snapshots](https://playwright.dev/docs/aria-snapshots)
- [Vitest Snapshot Testing](https://main.vitest.dev/guide/snapshot)