Snapshot Types
Insta has two major types of snapshots: named and inline snapshots. The former
are placed as separate .snap
files, the latter are stored inline in string
literals in the .rs
files.
Named snapshots are stored in the snapshots
folder right next to the test file
where this is used. The name of the file is <module>__<name>.snap
where
the name
of the snapshot. Snapshots can either be explicitly named or the
name is derived from the test name.
The format of snapshot files is documented here.
Implicitly Named Snapshots
All snapshot assertion functions let you leave out the snapshot name in
which case the snapshot name is derived from the test name (with an optional
leading test_
prefix removed.
This works because the rust test runner names the thread by the test name
and the name is taken from the thread name. In case your test spawns additional
threads this will not work and you will need to provide a name explicitly.
There are some situations in which rust test does not name or use threads.
In these cases insta will panic with an error. The backtrace
feature can
be enabled in which case insta will attempt to recover the test name from
the backtrace.
These are two assertions that use implicitly named snapshots:
#[test]
fn test_something() {
assert_snapshot!("first value");
assert_snapshot!("second value");
}
This creates two snapshots named something
and something-2
.
Named snapshots
Explicit snapshot naming can be useful to be more explicit when multiple snapshots are tested within one function as the default behavior would be to just count up the snapshot names.
To provide an explicit name provide the name of the snapshot as first argument to the macro:
#[test]
fn test_something() {
assert_snapshot!("first_snapshot", "first value");
assert_snapshot!("second_snapshot", "second value");
}
This will create two snapshots: first_snapshot
for the first value and
second_snapshot
for the second value.
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:
#[derive(Serialize)]
pub struct User {
username: String,
}
assert_yaml_snapshot!(User {
username: "john_doe".to_string(),
}, @"");
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. Note that inline
snapshots require the use of cargo-insta
.