Crate insta

source ·
Expand description

insta: a snapshot testing library for Rust

§What are snapshot tests

Snapshots tests (also sometimes called approval tests) are tests that assert values against a reference value (the snapshot). This is similar to how assert_eq! lets you compare a value against a reference value but unlike simple string assertions, snapshot tests let you test against complex values and come with comprehensive tools to review changes.

Snapshot tests are particularly useful if your reference values are very large or change often.

§What it looks like:

fn test_hello_world() {
    insta::assert_debug_snapshot!(vec![1, 2, 3]);

Where are the snapshots stored? Right next to your test in a folder called snapshots as individual .snap files.

Got curious?

§Writing Tests

use insta::assert_debug_snapshot;

fn test_snapshots() {
    assert_debug_snapshot!(vec![1, 2, 3]);

The recommended flow is to run the tests once, have them fail and check if the result is okay. By default the new snapshots are stored next to the old ones with the extra .new extension. Once you are satisfied move the new files over. To simplify this workflow you can use cargo insta review (requires cargo-insta) which will let you interactively review them:

$ cargo test
$ cargo insta review

§Use Without cargo-insta

Note that cargo-insta is entirely optional. You can also just use insta directly from cargo test and control it via the INSTA_UPDATE environment variable. The default is auto which will write all new snapshots into files if no CI is detected so that cargo-insta can pick them up. The following other modes are possible:

  • auto: the default. no for CI environments or new otherwise
  • always: overwrites old snapshot files with new ones unasked
  • unseen: behaves like always for new snapshots and new for others
  • new: write new snapshots into files
  • no: does not update snapshot files at all (just runs tests)

You can for instance first run the tests and not write and new snapshots, and if you like them run the tests again and update them:

INSTA_UPDATE=no cargo test
INSTA_UPDATE=always cargo test

§Assertion Macros

This crate exports multiple macros for snapshot testing:

The following macros require the use of serde’s Serialize:

For macros that work with serde this crate also permits redacting of partial values. See redactions in the documentation for more information.

§Snapshot updating

During test runs snapshots will be updated according to the INSTA_UPDATE environment variable. The default is auto which will write snapshots for any failing tests into files (if no CI is detected) so that cargo-insta can pick them up for review. Normally you don’t have to change this variable.


  • auto: the default. no for CI environments or new otherwise
  • new: writes snapshots for any failing tests into files, pending review
  • always: writes snapshots for any failing tests into .snap files, bypassing review
  • unseen: always for previously unseen snapshots or new for existing snapshots
  • no: does not write to snapshot files at all; just runs tests

When new, auto or unseen is used, the cargo-insta command can be used to review the snapshots conveniently:

$ cargo insta review

“enter” or “a” accepts a new snapshot, “escape” or “r” rejects, “space” or “s” skips the snapshot for now.

For more information read the cargo insta docs.

§Inline Snapshots

Additionally snapshots can also be stored inline. In that case the format for the snapshot macros is assert_snapshot!(reference_value, @"snapshot"). The leading at sign (@) indicates that the following string is the reference value. On review, cargo-insta will update the string with the new value.


assert_snapshot!(2 + 2, @"");

Like with normal snapshots, an initial test failure will write the proposed value into a draft file (note that inline snapshots use .pending-snap files rather than files). Running cargo insta review will review the proposed changes and update the source files on acceptance automatically.


The following features exist:

  • csv: enables CSV support (via serde)
  • json: enables JSON support (via serde)
  • ron: enables RON support (via serde)
  • toml: enables TOML support (via serde)
  • yaml: enables YAML support (via serde)
  • redactions: enables support for redactions
  • filters: enables support for filters
  • glob: enables support for globbing (glob!)
  • colors: enables color output (enabled by default)

For legacy reasons the json and yaml features are enabled by default in limited capacity. You will receive a deprecation warning if you are not opting into them but for now the macros will continue to function.

Enabling any of the serde based formats enables the hidden serde feature which gates some serde specific APIs such as Settings::set_info.


insta tries to be light in dependencies but this is tricky to accomplish given what it tries to do. By default it currently depends on serde for the assert_toml_snapshot! and assert_yaml_snapshot! macros. In the future this default dependencies will be removed. To already benefit from this optimization you can disable the default features and manually opt into what you want.


There are some settings that can be changed on a per-thread (and thus per-test) basis. For more information see Settings.

Additionally Insta will load a YAML config file with settings that change the behavior of insta between runs. It’s loaded from any of the following locations: .config/insta.yaml, insta.yaml and .insta.yaml from the workspace root. The following config options exist:

  # also set by INSTA_FORCE_UPDATE
  force_update: true/false
  require_full_match: true/false
  # also set by INSTA_FORCE_PASS
  force_pass: true/false
  # also set by INSTA_OUTPUT
  output: "diff" | "summary" | "minimal" | "none"
  # also set by INSTA_UPDATE
  update: "auto" | "always" | "new" | "unseen" | "no"
  # also set by INSTA_GLOB_FAIL_FAST
  glob_fail_fast: true/false

# these are used by cargo insta test
  # also set by INSTA_TEST_RUNNER
  runner: "auto" | "cargo-test" | "nextest"
  # automatically assume --review was passed to cargo insta test
  auto_review: true/false
  # automatically assume --accept-unseen was passed to cargo insta test
  auto_accept_unseen: true/false

# these are used by cargo insta review
  # also look for snapshots in ignored folders
  include_ignored: true / false
  # also look for snapshots in hidden folders
  include_hidden: true / false
  # show a warning if undiscovered (ignored or hidden) snapshots are found.
  # defaults to true but creates a performance hit.
  warn_undiscovered: true / false

§Optional: Faster Runs

Insta benefits from being compiled in release mode, even as dev dependency. It will compile slightly slower once, but use less memory, have faster diffs and just generally be more fun to use. To achieve that, opt insta and similar (the diffing library) into higher optimization in your Cargo.toml:

opt-level = 3

opt-level = 3

You can also disable the default features of insta which will cut down on the compile time a bit by removing some quality of life features.




  • Snapshot metadata information.
  • Configures how insta operates at test time.
  • A helper to work with stored snapshots.