---
name: snapshot-testing
description: "Use when output is meant for human eyes or a stable wire: rendered frames, JSON lines, help text, traces; pin it with insta and review the diff."
---

# Snapshot testing

The snapshot is documentation that fails when it lies.

## Shape

- One snapshot per rendered surface; name it after the surface and state (`help_top_level`, `rpc_prompt_then_abort`).
- Redact identity and time before snapshotting (ids, timestamps, paths, versions); a snapshot that changes every run is noise.
- Use structured snapshots (`assert_json_snapshot!`, `assert_yaml_snapshot!`) for data; string snapshots for text people read.
- Review every changed snapshot as code: read the `.snap.new` diff, accept only what the change intended, then rename it over the `.snap`.
- Snapshots live next to the test in `snapshots/`; commit them.

## Do not

- `INSTA_UPDATE=always` in CI or in a blind local run.
- Snapshot volatile or huge output; cut to the part under test.
- Use a snapshot where an assertion states the intent better.

## Sources

- [insta docs](https://insta.rs/docs/)