insta: a snapshot testing library for Rust
insta: a snapshot testing library for Rust
This crate exports multiple macros for snapshot testing:
assert_snapshot_matches! for comparing basic string snapshots.assert_debug_snapshot_matches! for comparing Debug outputs of values.assert_serialized_snapshot_matches! for comparing YAML serialized
output of types implementing serde::Serialize.assert_ron_snapshot_matches! for comparing RON serialized output of
types implementing serde::Serialize.assert_json_snapshot_matches! for comparing JSON serialized output of
types implementing serde::Serialize.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 has to be provided to the assertion macro.
For macros that work with serde::Serialize this crate also permits
redacting of partial values. See redactions for more
information.
Install insta and cargo-insta:
rust
$ cargo add --dev insta
$ cargo install cargo-insta
```rust use insta::assertdebugsnapshot_matches;
fn testsnapshots() { let value = vec![1, 2, 3]; assertdebugsnapshotmatches!("snapshot_name", value); } ```
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. You can also use cargo insta review which
will let you interactively review them:
rust
$ cargo test
$ cargo insta review
For more information on updating see [Snapshot Updating].
The committed snapshot files will have a header with some meta information that can make debugging easier and the snapshot:
created: "2019-01-21T22:03:13.792906+00:00" creator: insta@0.3.0 expression: "&User{id: Uuid::newv4(), username: \"johndoe\".to_string(),}"
[ 1, 2, 3 ] ```
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.
INSTA_UPDATE modes:
auto: the default. no for CI environments or new otherwisealways: overwrites old snapshot files with new ones unaskednew: write new snapshots into .snap.new files.no: does not update snapshot files at all (just runs tests)When new is used as mode the cargo-insta command can be used to review
the snapshots conveniently:
rust
$ cargo install cargo-insta
$ cargo test
$ 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 invoke cargo insta --help.
By default the tests will fail when the snapshot assertion fails. However if a test produces more than one snapshot it can be useful to force a test to pass so that all new snapshots are created in one go.
This can be enabled by setting INSTA_FORCE_PASS to 1:
rust
$ INSTA_FORCE_PASS=1 cargo test --no-fail-fast
For all snapshots created based on serde::Serialize output insta
supports redactions. This permits replacing values with hardcoded other
values to make snapshots stable when otherwise random or otherwise changing
values are involved.
Redactions can be defined as the third argument to those macros with
the syntax { selector => replacement_value }.
The following selectors exist:
.key: selects the given key["key"]: alternative syntax for keys[index]: selects the given index in an array[]: selects all items on an array[:end]: selects all items up to end (excluding, supports negative indexing)[start:]: selects all items starting with start[start:end]: selects all items from start to end (end excluding,
supports negative indexing)..*: selects all keys on that depthExample usage:
```rust
pub struct User { id: Uuid, username: String, }
assertserializedsnapshotmatches!("user", &User { id: Uuid::newv4(), username: "johndoe".tostring(), }, { ".id" => "[uuid]" }); ```
License: Apache-2.0