Crate insta

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:

#[test]
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?

• Read the introduction
• Read the main documentation which does not just cover the API of the crate but also many of the details of how it works.
• There is a screencast that shows the entire workflow: watch the insta introduction screencast.

Writing Tests

use insta::assert_debug_snapshot;

#[test]
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

Assertion Macros

This crate exports multiple macros for snapshot testing:

• assert_snapshot! for comparing basic string snapshots.
• assert_debug_snapshot! for comparing Debug outputs of values.
• assert_display_snapshot! for comparing Display outputs of values.

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

• assert_json_snapshot! for comparing JSON serialized output. (requires the json feature)
• assert_compact_json_snapshot! for comparing JSON serialized output while preferring single-line formatting. (requires the json feature)

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 all new snapshots into .snap.new files if no CI is detected so that cargo-insta can pick them up. Normally you don’t have to change this variable.

INSTA_UPDATE modes:

• 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 .snap.new files
• no: does not update snapshot files at all (just runs tests)

When new or auto is used as mode 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. cargo-insta will then update that string with the new value on review.

Example:

#[derive(Serialize)]
pub struct User {
   username: String,
}

assert_yaml_snapshot!(User {
   username: "john_doe".to_string(),
}, @"");

Like with normal snapshots after the initial test failure you can run cargo insta review to accept the change. The file will then be updated automatically.

Features

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.

Dependencies

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.

Settings

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:

behavior:
  # also set by INSTA_FORCE_UPDATE
  force_update: 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
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
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:

[profile.dev.package.insta]
opt-level = 3

[profile.dev.package.similar]
opt-level = 3

Modules

• internals
  Exposes some library internals.

Macros

• allow_duplicates
  Utility macro to permit a multi-snapshot run where all snapshots match.
• assert_compact_json_snapshot
  Asserts a Serialize snapshot in compact JSON format.
• assert_debug_snapshot
  Asserts a Debug snapshot.
• assert_display_snapshot
  Asserts a Display snapshot.
• assert_json_snapshot
  Asserts a Serialize snapshot in JSON format.
• assert_snapshot
  Asserts a string snapshot.
• with_settings
  Settings configuration macro.

Structs

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