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::Serialize
able value into a string by using one of the following macros:assert_json_snapshot!
,assert_yaml_snapshot!
,assert_toml_snapshot!
,assert_ron_snapshot!
, orassert_csv_snapshot!
. - You can instruct insta to use the
Debug
representation of a value by usingassert_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
"###);
}