1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! <div align="center">
//!  <img src="https://github.com/mitsuhiko/insta/blob/master/assets/logo.png?raw=true" width="250" height="250">
//!  <p><strong>insta: a snapshot testing library for Rust</strong></p>
//! </div>
//!
//! # How it Operates
//!
//! This crate exports three basic macros for snapshot testing:
//! `assert_snapshot_matches!` for comparing basic string snapshots,
//! `assert_debug_snapshot_matches!` for snapshotting the debug print output of
//! a type and the `assert_serialized_snapshot_matches!` macro becomes
//! available which serializes an object with `serde` to yaml before
//! snapshotting.
//!
//! 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.
//!
//! <img src="https://github.com/mitsuhiko/insta/blob/master/assets/insta.gif?raw=true" alt="">
//!
//! # Example
//!
//! Install `insta` and `cargo-insta`:
//!
//! ```ignore
//! $ cargo add --dev insta
//! $ cargo install cargo-insta
//! ```
//!
//! ```rust,ignore
//! use insta::assert_debug_snapshot_matches;
//!
//! #[test]
//! fn test_snapshots() {
//!     let value = vec![1, 2, 3];
//!     assert_debug_snapshot_matches!("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:
//!
//! ```ignore
//! $ cargo test
//! $ cargo insta review
//! ```
//!
//! For more information on updating see [Snapshot Updating].
//!
//! [Snapshot Updating]: #snapshot-updating
//!
//! # Snapshot files
//!
//! The committed snapshot files will have a header with some meta information
//! that can make debugging easier and the snapshot:
//!
//! ```ignore
//! ---
//! created: "2019-01-21T22:03:13.792906+00:00"
//! creator: insta@0.3.0
//! expression: "&User{id: Uuid::new_v4(), username: \"john_doe\".to_string(),}"
//! source: tests/test_redaction.rs
//! ---
//! [
//!     1,
//!     2,
//!     3
//! ]
//! ```
//!
//! # 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.
//!
//! `INSTA_UPDATE` modes:
//!
//! - `auto`: the default. `no` for CI environments or `new` otherwise
//! - `always`: overwrites old snapshot files with new ones unasked
//! - `new`: 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:
//!
//! ```ignore
//! $ 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`.
//!
//! # Test Assertions
//!
//! 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`:
//!
//! ```ignore
//! $ INSTA_FORCE_PASS=1 cargo test --no-fail-fast
//! ```
#[macro_use]
mod macros;
mod redaction;
mod runtime;
mod serialization;

#[cfg(test)]
mod test;

pub use crate::runtime::Snapshot;

// this should eventually become public api but probably somewhere else
#[doc(hidden)]
pub use crate::redaction::Selector;
#[doc(hidden)]
pub use serde_yaml::{Mapping, Number, Sequence, Value};

#[doc(hidden)]
pub mod _macro_support {
    pub use crate::runtime::assert_snapshot;
    pub use crate::serialization::{serialize_value, serialize_value_redacted};
}