[test-infra][1/n] Replace Move's .exp tests with cargo-insta (#21003)

## Description - This PR adds a wrapper around `insta::assert_snapshot` to ease migration from `.exp` files - Utilize this for `move-docgen-testsuite` (which was already using snapshot) - Moves snapshot files next to the `toml` files ## Test plan - 👀 --- ## Release notes Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required. For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates. - [ ] Protocol: - [ ] Nodes (Validators and Full nodes): - [ ] gRPC: - [ ] JSON-RPC: - [ ] GraphQL: - [ ] CLI: - [ ] Rust SDK:
MystenLabs · Jan 29, 2025 · 8e6047e · 8e6047e
1 parent 37743e3
commit 8e6047e
Show file tree

Hide file tree

Showing 27 changed files with 308 additions and 1,390 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/external-crates/move/Cargo.lock b/external-crates/move/Cargo.lock
diff --git a/external-crates/move/crates/move-command-line-common/Cargo.toml b/external-crates/move/crates/move-command-line-common/Cargo.toml
@@ -20,6 +20,7 @@ serde.workspace = true
 dirs-next.workspace = true
 vfs.workspace = true
 bcs.workspace = true
+insta = { workspace = true, features = ["serde"] }
 
 move-core-types.workspace = true
 move-binary-format.workspace = true

diff --git a/external-crates/move/crates/move-command-line-common/src/testing.rs b/external-crates/move/crates/move-command-line-common/src/testing.rs
@@ -63,3 +63,132 @@ pub fn format_diff(expected: impl AsRef<str>, actual: impl AsRef<str>) -> String
     }
     ret
 }
+
+/// See `insta_assert!` for documentation.
+pub struct InstaOptions<Info: serde::Serialize, Suffix: Into<String>> {
+    pub info: Option<Info>,
+    pub suffix: Option<Suffix>,
+}
+
+impl<Info: serde::Serialize, Suffix: Into<String>> InstaOptions<Info, Suffix> {
+    /// See `insta_assert!` for documentation.
+    pub fn new() -> Self {
+        Self {
+            info: None,
+            suffix: None,
+        }
+    }
+}
+
+impl InstaOptions<(), String> {
+    /// See `insta_assert!` for documentation.
+    pub fn none() -> Self {
+        Self {
+            info: None,
+            suffix: None,
+        }
+    }
+}
+
+#[macro_export]
+/// A wrapper around `insta::assert_snapshort` to promote uniformity in the Move codebase, intended
+/// to be used with datatest-stable and as a replacement for the hand-rolled baseline tests.
+/// The snapshot file will be saved in the same directory as the input file with the name specified.
+/// In essence, it will be saved at the path `{input_path}/{name}.snap` (and
+/// `{input_path}/{name}@{suffix}.snap` if `suffix` is specified).
+///
+/// For ease of use and reviewing, `insta_assert` should be used at most once per test. When it
+/// fails, it will stop the test. So if there are multiple snapshots in a given test, it would
+/// require multiple test runs to review all the failures.
+/// If you do need multiple snapshots in a test, you may want to disable assertions for your test
+/// run by setting `INSTA_FORCE_PASS=1` see
+/// https://insta.rs/docs/advanced/#disabling-assertion-failure for more information.
+///
+/// # Arguments
+/// The macro has three required arguments:
+///
+/// - `name`: The name of the test. This will be used to name the snapshot file. For datatest this
+///           should likely be the file name.
+/// - `input_path`: The path to the input file. This is used to determine the snapshot path.
+/// - `contents`: The contents to snapshot.
+///
+///
+/// The macro also accepts an optional arguments to that are used with `InstaOptions` to customize
+/// the snapshot. If needed the `InstaOptions` struct can be used directly by specifying the
+/// `options` argument. Options include:
+///
+///  - `info`: Additional information to include in the header of the snapshot file. This can be
+///           useful for debugging tests. The value can be any type that implements
+///           `serde::Serialize`.
+/// - `suffix`: A suffix to append to the snapshot file name. This changes the snapshot path to
+///            `{input_path}/{name}@{suffix}.snap`.
+///
+/// # Updating snapshots
+///
+/// After running the test, the `.snap` files can be updated in two ways:
+///
+/// 1. By using `cargo insta review`, which will open an interactive UI to review the changes.
+/// 2. Running the tests with the environment variable `INSTA_UPDATE=alawys`
+///
+/// See https://docs.rs/insta/latest/insta/#updating-snapshots for more information.
+macro_rules! insta_assert {
+    {
+        name: $name:expr,
+        input_path: $input:expr,
+        contents: $contents:expr,
+        options: $options:expr
+        $(,)?
+    } => {{
+        let name: String = $name.into();
+        let i: &std::path::Path = $input.as_ref();
+        let i = i.canonicalize().unwrap();
+        let c = $contents;
+        let $crate::testing::InstaOptions { info, suffix } = $options;
+        let mut settings = insta::Settings::clone_current();
+        settings.set_input_file(&i);
+        settings.set_snapshot_path(i.parent().unwrap());
+        if let Some(info) = info {
+            settings.set_info(info);
+        }
+        if let Some(suffix) = suffix {
+            settings.set_snapshot_suffix(suffix);
+        }
+        settings.set_prepend_module_to_snapshot(false);
+        settings.set_omit_expression(true);
+        settings.bind(|| {
+            insta::assert_snapshot!(name, c);
+        });
+    }};
+    {
+        name: $name:expr,
+        input_path: $input:expr,
+        contents: $contents:expr
+        $(,)?
+    } => {{
+        insta_assert! {
+            name: $name,
+            input_path: $input,
+            output_path: $output,
+            contents: $contents,
+            options: $crate::testing::InstaOptions::none(),
+        }
+    }};
+    {
+        name: $name:expr,
+        input_path: $input:expr,
+        contents: $contents:expr,
+        $($k:ident: $v:expr),+$(,)?
+    } => {{
+        let mut opts = $crate::testing::InstaOptions::new();
+        $(
+            opts.$k = Some($v);
+        )+
+        insta_assert! {
+            name: $name,
+            input_path: $input,
+            contents: $contents,
+            options: opts
+        }
+    }};
+}
+pub use insta_assert;
diff --git a/...otation__collapsed_sections__a__m.md.snap → ...nnotation/a__m.md@collapsed_sections.snap b/...otation__collapsed_sections__a__m.md.snap → ...nnotation/a__m.md@collapsed_sections.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/annotation/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/...__move__annotation__default__a__m.md.snap → ...ests/move/annotation/a__m.md@default.snap b/...__move__annotation__default__a__m.md.snap → ...ests/move/annotation/a__m.md@default.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/annotation/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/...e_block__collapsed_sections__a__m.md.snap → ...ode_block/a__m.md@collapsed_sections.snap b/...e_block__collapsed_sections__a__m.md.snap → ...ode_block/a__m.md@collapsed_sections.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/code_block/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/...__move__code_block__default__a__m.md.snap → ...ests/move/code_block/a__m.md@default.snap b/...__move__code_block__default__a__m.md.snap → ...ests/move/code_block/a__m.md@default.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/code_block/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/...move__const_string__default__a__m.md.snap → ...st_string/a__m.md@collapsed_sections.snap b/...move__const_string__default__a__m.md.snap → ...st_string/a__m.md@collapsed_sections.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/const_string/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/..._string__collapsed_sections__a__m.md.snap → ...ts/move/const_string/a__m.md@default.snap b/..._string__collapsed_sections__a__m.md.snap → ...ts/move/const_string/a__m.md@default.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/const_string/Move.toml
 ---
 <a name="a_m"></a>
 

diff --git a/...ilities__collapsed_sections__a__m.md.snap → ...ibilities/a__m.md@collapsed_sections.snap b/...ilities__collapsed_sections__a__m.md.snap → ...ibilities/a__m.md@collapsed_sections.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/different_visibilities/Move.toml
 ---
 <a name="a_TestViz"></a>
 

diff --git a/...erent_visibilities__default__a__m.md.snap → ...fferent_visibilities/a__m.md@default.snap b/...erent_visibilities__default__a__m.md.snap → ...fferent_visibilities/a__m.md@default.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: false
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/different_visibilities/Move.toml
 ---
 <a name="a_TestViz"></a>
 

diff --git a/...__enums__collapsed_sections__a__m.md.snap → ...ove/enums/a__m.md@collapsed_sections.snap b/...__enums__collapsed_sections__a__m.md.snap → ...ove/enums/a__m.md@collapsed_sections.snap
@@ -1,6 +1,14 @@
 ---
 source: crates/move-docgen-tests/tests/testsuite.rs
-expression: contents
+info:
+  section_level_start: 1
+  exclude_private_fun: false
+  exclude_impl: false
+  toc_depth: 3
+  no_collapsed_sections: true
+  include_dep_diagrams: false
+  include_call_diagrams: false
+input_file: crates/move-docgen-tests/tests/move/enums/Move.toml
 ---
 <a name="a_m"></a>