Merge branch 'master' of github.com:mitsuhiko/insta

.github/workflows/tests.yml

@@ -2,6 +2,11 @@ name: Tests
 
 on: [push, pull_request]
 
+env:
+  CARGO_TERM_COLOR: always
+  CLICOLOR_FORCE: 1
+  RUSTDOCFLAGS: "-Dwarnings"
+
 jobs:
   test-latest:
     name: Test on Latest
@@ -47,3 +52,15 @@ jobs:
           perl -ni -e 'print unless /\[profile\.dist\]/ .. eof' Cargo.toml
       - name: Check
         run: cargo check -p insta --no-default-features
+
+  build-docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v2
+      - name: doc
+        run: cargo doc --all-features

cargo-insta/src/inline.rs

@@ -171,6 +171,14 @@ impl FilePatcher {
             }
 
             fn try_extract_snapshot(&mut self, tokens: &[TokenTree], indentation: usize) -> bool {
+                // ignore optional trailing comma
+                let tokens = match tokens.last() {
+                    Some(TokenTree::Punct(ref punct)) if punct.as_char() == ',' => {
+                        &tokens[..tokens.len() - 1]
+                    }
+                    _ => tokens,
+                };
+
                 if tokens.len() < 2 {
                     return false;
                 }

cargo-insta/src/walk.rs

@@ -35,8 +35,7 @@ pub(crate) fn find_snapshots<'a>(
             let fname = e.file_name().to_string_lossy();
             if fname.ends_with(".new") {
                 let new_path = e.into_path();
-                let mut old_path = new_path.clone();
-                old_path.set_extension("");
+                let old_path = new_path.clone().with_extension("");
                 Some(SnapshotContainer::load(
                     new_path,
                     old_path,

cargo-insta/tests/snapshots/main__test_basic_utf8_inline.snap

@@ -1,7 +1,6 @@
 ---
-source: src/main.rs
+source: cargo-insta/tests/main.rs
 expression: "&fs::read_to_string(gen_file).unwrap()"
-input_file: tests/test_basic_utf8_inline.rs
 ---
 #[test]
 #[rustfmt::skip]
@@ -22,3 +21,10 @@ fn test_remove_existing_value_multiline() {
     );
 }
 
+#[test]
+fn test_trailing_comma_in_inline_snapshot() {
+    insta::assert_snapshot!(
+        "new value",
+        @"new value",  // comma here
+    );
+}

cargo-insta/tests/snapshots/main__test_json_inline.snap

@@ -1,7 +1,6 @@
 ---
-source: src/main.rs
+source: cargo-insta/tests/main.rs
 expression: "&fs::read_to_string(gen_file).unwrap()"
-input_file: tests/test_json_inline.rs
 ---
 use serde::Serialize;
 
@@ -27,3 +26,34 @@ fn test_json_snapshot() {
     "###);
 }
 
+#[test]
+fn test_json_snapshot_trailing_comma() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_compact_json_snapshot!(
+        &user,
+        @r###"{"id": 42, "email": "john.doe@example.com"}"###,
+    );
+}
+
+#[test]
+fn test_json_snapshot_trailing_comma_redaction() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_json_snapshot!(
+        &user,
+        {
+            ".id" => "[user_id]",
+        },
+        @r###"
+    {
+      "id": "[user_id]",
+      "email": "john.doe@example.com"
+    }
+    "###,
+    );
+}

cargo-insta/tests/snapshots/main__test_yaml_inline.snap

@@ -1,7 +1,6 @@
 ---
-source: src/main.rs
+source: cargo-insta/tests/main.rs
 expression: "&fs::read_to_string(gen_file).unwrap()"
-input_file: tests/test_yaml_inline.rs
 ---
 use serde::Serialize;
 
@@ -26,3 +25,21 @@ fn test_yaml_snapshot() {
     "###);
 }
 
+#[test]
+fn test_yaml_snapshot_trailing_comma() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_yaml_snapshot!(
+        &user,
+        {
+            ".id" => "[user_id]",
+        },
+        @r###"
+    ---
+    id: "[user_id]"
+    email: john.doe@example.com
+    "###,
+    );
+}

cargo-insta/tests/test-input/test_basic_utf8_inline.rs

@@ -18,3 +18,11 @@ fn test_remove_existing_value_multiline() {
         it really is"
     );
 }
+
+#[test]
+fn test_trailing_comma_in_inline_snapshot() {
+    insta::assert_snapshot!(
+        "new value",
+        @"old value",  // comma here
+    );
+}

cargo-insta/tests/test-input/test_json_inline.rs

@@ -16,3 +16,30 @@ fn test_json_snapshot() {
         ".id" => "[user_id]",
     }, @"");
 }
+
+#[test]
+fn test_json_snapshot_trailing_comma() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_compact_json_snapshot!(
+        &user,
+        @"",
+    );
+}
+
+#[test]
+fn test_json_snapshot_trailing_comma_redaction() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_json_snapshot!(
+        &user,
+        {
+            ".id" => "[user_id]",
+        },
+        @"",
+    );
+}

cargo-insta/tests/test-input/test_yaml_inline.rs

@@ -16,3 +16,18 @@ fn test_yaml_snapshot() {
         ".id" => "[user_id]",
     }, @"");
 }
+
+#[test]
+fn test_yaml_snapshot_trailing_comma() {
+    let user = User {
+        id: 42,
+        email: "john.doe@example.com".into(),
+    };
+    insta::assert_yaml_snapshot!(
+        &user,
+        {
+            ".id" => "[user_id]",
+        },
+        @"",
+    );
+}

insta/src/lib.rs

@@ -100,56 +100,55 @@
 //! # 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 so that
-//! [`cargo-insta`](https://crates.io/crates/cargo-insta)
-//! can pick them up.  Normally you don't have to change this variable.
+//! environment variable.  The default is `auto` which will write snapshots for
+//! any failing tests into `.snap.new` files (if no CI is detected) so that
+//! [`cargo-insta`](https://crates.io/crates/cargo-insta) can pick them up for
+//! review. Normally you don't have to change this variable.
 //!
 //! `INSTA_UPDATE` modes:
 //!
 //! - `auto`: the default. `no` for CI environments or `new` otherwise
-//! - `always`: overwrites old snapshot files with new ones unasked
-//! - `unseen`: behaves like `always` for new snapshots and `new` for others
-//! - `new`: write new snapshots into `.snap.new` files
-//! - `no`: does not update snapshot files at all (just runs tests)
-//!
-//! When `new` or `auto` is used as mode the [`cargo-insta`](https://crates.io/crates/cargo-insta)
-//! command can be used to review the snapshots conveniently:
+//! - `new`: writes snapshots for any failing tests into `.snap.new` files,
+//!   pending review
+//! - `always`: writes snapshots for any failing tests into `.snap` files,
+//!   bypassing review
+//! - `unseen`: `always` for previously unseen snapshots or `new` for existing
+//!   snapshots
+//! - `no`: does not write to snapshot files at all; just runs tests
+//!
+//! When `new`, `auto` or `unseen` is used, the
+//! [`cargo-insta`](https://crates.io/crates/cargo-insta) command can be used to
+//! review the snapshots conveniently:
 //!
 //! ```text
 //! $ cargo insta review
 //! ```
 //!
-//! "enter" or "a" accepts a new snapshot, "escape" or "r" rejects,
-//! "space" or "s" skips the snapshot for now.
+//! "enter" or "a" accepts a new snapshot, "escape" or "r" rejects, "space" or
+//! "s" skips the snapshot for now.
 //!
-//! For more information [read the cargo insta docs](https://insta.rs/docs/cli/).
+//! For more information [read the cargo insta
+//! docs](https://insta.rs/docs/cli/).
 //!
 //! # Inline Snapshots
 //!
 //! Additionally 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.
+//! reference value.  On review, `cargo-insta` will update the string with the
+//! new value.
 //!
 //! Example:
 //!
-#![cfg_attr(feature = "yaml", doc = " ```no_run")]
-#![cfg_attr(not(feature = "yaml"), doc = " ```ignore")]
-//! # use insta::*; use serde::Serialize;
-//! #[derive(Serialize)]
-//! pub struct User {
-//!     username: String,
-//! }
-//!
-//! assert_yaml_snapshot!(User {
-//!     username: "john_doe".to_string(),
-//! }, @"");
+//! ```no_run
+//! # use insta::assert_snapshot;
+//! assert_snapshot!(2 + 2, @"");
 //! ```
 //!
-//! Like with normal snapshots after the initial test failure you can run
-//! `cargo insta review` to accept the change.  The file will then be updated
+//! Like with normal snapshots, an initial test failure will write the proposed
+//! value into a draft file (note that inline snapshots use `.pending-snap`
+//! files rather than `.snap.new` files). Running `cargo insta review` will
+//! review the proposed changes and update the source files on acceptance
 //! automatically.
 //!
 //! # Features
@@ -166,9 +165,9 @@
 //! * `glob`: enables support for globbing ([`glob!`])
 //! * `colors`: enables color output (enabled by default)
 //!
-//! For legacy reasons the `json` and `yaml` features are enabled by default
-//! in limited capacity.  You will receive a deprecation warning if you are
-//! not opting into them but for now the macros will continue to function.
+//! For legacy reasons the `json` and `yaml` features are enabled by default in
+//! limited capacity.  You will receive a deprecation warning if you are not
+//! opting into them but for now the macros will continue to function.
 //!
 //! Enabling any of the serde based formats enables the hidden `serde` feature
 //! which gates some serde specific APIs such as [`Settings::set_info`].
@@ -177,10 +176,10 @@
 //!
 //! `insta` tries to be light in dependencies but this is tricky to accomplish
 //! given what it tries to do.  By default it currently depends on `serde` for
-//! the [`assert_toml_snapshot!`] and [`assert_yaml_snapshot!`] macros.  In
-//! the future this default dependencies will be removed.  To already benefit
-//! from this optimization you can disable the default features and manually
-//! opt into what you want.
+//! the [`assert_toml_snapshot!`] and [`assert_yaml_snapshot!`] macros.  In the
+//! future this default dependencies will be removed.  To already benefit from
+//! this optimization you can disable the default features and manually opt into
+//! what you want.
 //!
 //! # Settings
 //!
@@ -229,10 +228,11 @@
 //!
 //! # Optional: Faster Runs
 //!
-//! Insta benefits from being compiled in release mode, even as dev dependency.  It
-//! will compile slightly slower once, but use less memory, have faster diffs and
-//! just generally be more fun to use.  To achieve that, opt `insta` and `similar`
-//! (the diffing library) into higher optimization in your `Cargo.toml`:
+//! Insta benefits from being compiled in release mode, even as dev dependency.
+//! It will compile slightly slower once, but use less memory, have faster diffs
+//! and just generally be more fun to use.  To achieve that, opt `insta` and
+//! `similar` (the diffing library) into higher optimization in your
+//! `Cargo.toml`:
 //!
 //! ```yaml
 //! [profile.dev.package.insta]