Getting Started

So you want to get started with snapshot testing? Here is the 5 minute introduction to how to be successful with insta.

Installation

The recommended way is to add the dependency with cargo-edit if you have it:

cargo add --dev insta

Alternatively edit your Cargo.toml manually and add insta as manual dependency:

[dev-dependencies]
insta = "1.7.0"

And for an improved review experience it's recommended to install the cargo-insta tool:

cargo install cargo-insta

Writing Tests

Insta snapshots reference values which are fundamentally strings. However the method by which these strings are generated can be split in three different ways:

• You can stringify a reference value yourself and assert on it with assert_snapshot!.
• You can have insta serialize a serde::Serializeable value into a string by using one of the following macros: assert_json_snapshot!, assert_yaml_snapshot!, assert_toml_snapshot!, assert_ron_snapshot!, or assert_csv_snapshot!.
• You can instruct insta to use the Debug representation of a value by using assert_debug_snapshot!.

For most real world applications the recommendation is to use YAML snapshots of serializable values. This is because they look best under version control and the diff viewer and support redactions.

The following example demonstrates a very simple test case:

fn split_words(s: &str) -> Vec<&str> {
    s.split_whitespace().collect()
}

#[test]
fn test_split_words() {
    let words = split_words("hello from the other side");
    insta::assert_yaml_snapshot!(words);
}

Reviewing Snapshots

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 insta review

For more information see cargo-insta documentation.

Inline Snapshots

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.

This is the example above with inline snapshots:

fn split_words(s: &str) -> Vec<&str> {
    s.split_whitespace().collect()
}

#[test]
fn test_split_words() {
    let words = split_words("hello from the other side");
    insta::assert_yaml_snapshot!(words, @"");
}

After the initial test failure you can run cargo insta review to accept the change. The file will then be updated automatically and the reference value will be placed in the macro invocation like this:

fn split_words(s: &str) -> Vec<&str> {
    s.split_whitespace().collect()
}

#[test]
fn test_split_words() {
    let words = split_words("hello from the other side");
    insta::assert_yaml_snapshot!(words, @r###"
    ---
    - hello
    - from
    - the
    - other
    - side
    "###);
}