Auto merge of #10581 - epage:snapbox, r=ehuss

Integrate snapbox in with cargo-test-support

### What does this PR try to resolve?

#10472 introduced snapbox to cargo's tests in the least intrusive manner by copying some cargo-test-support code.  Primarily, this PR works to de-duplicate that code.  Secondarily, it makes it possible for snapbox to be used by other cargo tests that can work with its more limited functionality compared to cargo-test-support.

### How should we test and review this PR?

This is broken down by commits for smaller chunks to look over with some extra details in some of the commit messages.

As this is effectively refactoring existing tests, them passing is sufficient for testing.  The main focus would be on any API design including if there are any practices that we used to do that this continues forward to snapbox that we shouldn't.

### Additional information

The cargo contributing guide also needs to be updated but I'm leaving that off for another PR once this is merged so we have a clearer idea of what the API will look like (less churn) and so we can focus the conversation for each PR.

Author: bors

crates/cargo-test-support/Cargo.toml

@@ -11,6 +11,7 @@ doctest = false
 anyhow = "1.0.34"
 cargo-test-macro = { path = "../cargo-test-macro" }
 cargo-util = { path = "../cargo-util" }
+snapbox = { version = "0.2.8", features = ["diff", "path"] }
 filetime = "0.2"
 flate2 = { version = "1.0", default-features = false, features = ["zlib"] }
 git2 = "0.14.2"

crates/cargo-test-support/src/compare.rs

@@ -41,6 +41,57 @@ use std::path::Path;
 use std::str;
 use url::Url;
 
+/// Default `snapbox` Assertions
+///
+/// # Snapshots
+///
+/// Updating of snapshots is controlled with the `SNAPSHOTS` environment variable:
+///
+/// - `skip`: do not run the tests
+/// - `ignore`: run the tests but ignore their failure
+/// - `verify`: run the tests
+/// - `overwrite`: update the snapshots based on the output of the tests
+///
+/// # Patterns
+///
+/// - `[..]` is a character wildcard, stopping at line breaks
+/// - `\n...\n` is a multi-line wildcard
+/// - `[EXE]` matches the exe suffix for the current platform
+/// - `[ROOT]` matches [`paths::root()`][crate::paths::root]
+/// - `[ROOTURL]` matches [`paths::root()`][crate::paths::root] as a URL
+///
+/// # Normalization
+///
+/// In addition to the patterns described above, text is normalized
+/// in such a way to avoid unwanted differences. The normalizations are:
+///
+/// - Backslashes are converted to forward slashes to deal with Windows paths.
+///   This helps so that all tests can be written assuming forward slashes.
+///   Other heuristics are applied to try to ensure Windows-style paths aren't
+///   a problem.
+/// - Carriage returns are removed, which can help when running on Windows.
+pub fn assert() -> snapbox::Assert {
+    let root = paths::root();
+    // Use `from_file_path` instead of `from_dir_path` so the trailing slash is
+    // put in the users output, rather than hidden in the variable
+    let root_url = url::Url::from_file_path(&root).unwrap().to_string();
+    let root = root.display().to_string();
+
+    let mut subs = snapbox::Substitutions::new();
+    subs.extend([
+        (
+            "[EXE]",
+            std::borrow::Cow::Borrowed(std::env::consts::EXE_SUFFIX),
+        ),
+        ("[ROOT]", std::borrow::Cow::Owned(root)),
+        ("[ROOTURL]", std::borrow::Cow::Owned(root_url)),
+    ])
+    .unwrap();
+    snapbox::Assert::new()
+        .action_env(snapbox::DEFAULT_ACTION_ENV)
+        .substitutions(subs)
+}
+
 /// Normalizes the output so that it can be compared against the expected value.
 fn normalize_actual(actual: &str, cwd: Option<&Path>) -> String {
     // It's easier to read tabs in outputs if they don't show up as literal