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:

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

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 satisifed move the new files over. To simplify this workflow you can use cargo insta review 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.
  • assert_csv_snapshot! for comparing CSV serialized output of types implementing serde::Serialize. (requires the csv feature)
  • assert_toml_snapshot! for comparing TOML serialized output of types implementing serde::Serialize. (requires the toml feature)
  • assert_yaml_snapshot! for comparing YAML serialized output of types implementing serde::Serialize.
  • assert_ron_snapshot! for comparing RON serialized output of types implementing serde::Serialize. (requires the ron feature)
  • assert_json_snapshot! for comparing JSON serialized output of types implementing serde::Serialize.

For macros that work with serde::Serialize 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:

Settings

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

Modules

Exposes some library internals.

Macros

Asserts a Serialize snapshot in CSV format.

Asserts a Debug snapshot.

Asserts a Display snapshot.

Asserts a Serialize snapshot in JSON format.

Asserts a Serialize snapshot in RON format.

Asserts a string snapshot.

Asserts a Serialize snapshot in TOML format.

Asserts a Serialize snapshot in YAML format.

Executes a closure for all input files matching a glob.

Settings configuration macro.

Structs

Snapshot metadata information.

Configures how insta operates at test time.

A helper to work with stored snapshots.

Functions

Creates a dynamic redaction.