Added better filesystem layout testing harness (#15874)

### What does this PR try to resolve?

The goal is to make filesystem layout tests easier to understand and
review.
The `build-dir` test's have a [helper
fns](https://github.com/rust-lang/cargo/blob/master/tests/testsuite/build_dir.rs#L720)
that have imperative checks. While this works, its not easy to see what
its validating at a glance.

My thought is to reuse the snapbox infrastructure we already have for
the cargo ui tests.
The prototype in this PR generates a file tree (like the unix tree
command) and uses snapbox to compare against a snapshot. This makes the
layout tests much easier to read and failures are much more obvious what
what went wrong.

### Implementation Details

* The `LayoutTree` struct handles comparison logic (as opposed to using
snapbox directly)
* This avoids the issues initial implementation (ordering and platform
specific files, see full details below)
* If the comparison fails, 2 human readable tree's are generated and
snapbox is used to display the diffs.
* Note: These diffs are in-memory thus, do not support
`SNAPSHOTS=overwrite`. This is arguably good as often the overwrite
would be incorrect as the snapshots are platform specific.
* Snapshots would support conditional files based on the target os /
platform env
* Files/directories may be suffixed with
`[target_platform=<target-platform>]`
  * Multiple platforms may be specified separated by comma

<details><summary>initial implementation issues</summary>

However there are some problems with the current implementation that
limit the usefulness of it.

1. Different platforms have different files which cause some tests to
fail
   * Examples
      * lib prefix/suffixes based on platform
      * `dSYM` on macos
* One idea I have would be to have a cfg suffix after file name in the
tree like so
     * `└── foo-[HASH].dSYM [cfg(target_os = "macos")]`
* This would also require rethinking the "tree lines" (`└`, `├`, `│`) to
handle optional files.
2. When dealing with build scripts there are multiple
`target/<profile>/build/pkg-[HASH]` directories. The hash changes the
order of the directories when generating the tree making snapshots
inconsistent.
* We have redactions to handle replacing the hash with a placeholder
`[HASH]`, but this does not help with the order.

</details>

---

Fun fact: These changes were written and tested at [Rust Forge
2025](https://rustforgeconf.com/) in New Zealand. 🇳🇿
🥳

Author: epage

Cargo.lock

@@ -32,7 +32,7 @@ cargo-credential-macos-keychain = { version = "0.4.18", path = "credential/cargo
 cargo-credential-wincred = { version = "0.4.18", path = "credential/cargo-credential-wincred" }
 cargo-platform = { path = "crates/cargo-platform", version = "0.3.0" }
 cargo-test-macro = { version = "0.4.7", path = "crates/cargo-test-macro" }
-cargo-test-support = { version = "0.8.2", path = "crates/cargo-test-support" }
+cargo-test-support = { version = "0.9.0", path = "crates/cargo-test-support" }
 cargo-util = { version = "0.2.25", path = "crates/cargo-util" }
 cargo-util-schemas = { version = "0.10.1", path = "crates/cargo-util-schemas" }
 cargo_metadata = "0.21.0"

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cargo-test-support"
-version = "0.8.2"
+version = "0.9.0"
 edition.workspace = true
 rust-version = "1.90"  # MSRV:1
 license.workspace = true

crates/cargo-test-support/Cargo.toml

@@ -229,6 +229,12 @@ fn add_regex_redactions(subs: &mut snapbox::Redactions) {
     .unwrap();
     subs.insert("[HASH]", regex!(r"/[a-z0-9\-_]+-(?<redacted>[0-9a-f]{16})"))
         .unwrap();
+    // Match multi-part hashes like `06/b451d0d6f88b1d` used in directory paths
+    subs.insert("[HASH]", regex!(r"/(?<redacted>[a-f0-9]{2}\/[0-9a-f]{14})"))
+        .unwrap();
+    // Match file name hashes like `foo-06b451d0d6f88b1d`
+    subs.insert("[HASH]", regex!(r"[a-z0-9]+-(?<redacted>[a-f0-9]{16})"))
+        .unwrap();
     subs.insert(
         "[AVG_ELAPSED]",
         regex!(r"(?<redacted>[0-9]+(\.[0-9]+)?) ns/iter"),

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

@@ -1,6 +1,8 @@
 //! Access common paths and manipulate the filesystem
 
 use filetime::FileTime;
+use itertools::Itertools;
+use walkdir::WalkDir;
 
 use std::cell::RefCell;
 use std::env;
@@ -12,6 +14,9 @@ use std::sync::Mutex;
 use std::sync::OnceLock;
 use std::sync::atomic::{AtomicUsize, Ordering};
 
+use crate::compare::assert_e2e;
+use crate::compare::match_contains;
+
 static CARGO_INTEGRATION_TEST_DIR: &str = "cit";
 
 static GLOBAL_ROOT: OnceLock<Mutex<Option<PathBuf>>> = OnceLock::new();
@@ -152,6 +157,10 @@ pub trait CargoPathExt {
     fn move_in_time<F>(&self, travel_amount: F)
     where
         F: Fn(i64, u32) -> (i64, u32);
+
+    fn assert_build_dir_layout(&self, expected: impl snapbox::IntoData);
+
+    fn assert_dir_layout(&self, expected: impl snapbox::IntoData, ignored_path_patterns: &[String]);
 }
 
 impl CargoPathExt for Path {
@@ -236,6 +245,43 @@ impl CargoPathExt for Path {
             });
         }
     }
+
+    #[track_caller]
+    fn assert_build_dir_layout(&self, expected: impl snapbox::IntoData) {
+        // We call `unordered()` here to because the build-dir has some scenarios that make
+        // consistent ordering not possible.
+        // Notably:
+        // 1. Binaries with `.exe` on Windows causing the ordering to change with the dep-info `.d`
+        //    file.
+        // 2. Directories with hashes are often reordered differently by platform.
+        self.assert_dir_layout(expected.unordered(), &build_dir_ignored_path_patterns());
+    }
+
+    #[track_caller]
+    fn assert_dir_layout(
+        &self,
+        expected: impl snapbox::IntoData,
+        ignored_path_patterns: &[String],
+    ) {
+        let assert = assert_e2e();
+        let actual = WalkDir::new(self)
+            .sort_by_file_name()
+            .into_iter()
+            .filter_map(|e| e.ok())
+            .filter(|e| e.file_type().is_file())
+            .map(|e| e.path().to_string_lossy().into_owned())
+            .filter(|file| {
+                for ignored in ignored_path_patterns {
+                    if match_contains(&ignored, file, &assert.redactions()).is_ok() {
+                        return false;
+                    }
+                }
+                return true;
+            })
+            .join("\n");
+
+        assert.eq(format!("{actual}\n"), expected);
+    }
 }
 
 impl CargoPathExt for PathBuf {
@@ -260,6 +306,21 @@ impl CargoPathExt for PathBuf {
     {
         self.as_path().move_in_time(travel_amount)
     }
+
+    #[track_caller]
+    fn assert_build_dir_layout(&self, expected: impl snapbox::IntoData) {
+        self.as_path().assert_build_dir_layout(expected);
+    }
+
+    #[track_caller]
+    fn assert_dir_layout(
+        &self,
+        expected: impl snapbox::IntoData,
+        ignored_path_patterns: &[String],
+    ) {
+        self.as_path()
+            .assert_dir_layout(expected, ignored_path_patterns);
+    }
 }
 
 fn do_op<F>(path: &Path, desc: &str, mut f: F)
@@ -290,6 +351,20 @@ where
     }
 }
 
+/// The paths to ignore when [`CargoPathExt::assert_build_dir_layout`] is called
+fn build_dir_ignored_path_patterns() -> Vec<String> {
+    vec![
+        // Ignore MacOS debug symbols as there are many files/directories that would clutter up
+        // tests few not a lot of benefit.
+        "[..].dSYM/[..]",
+        // Ignore Windows debub symbols files (.pdb)
+        "[..].pdb",
+    ]
+    .into_iter()
+    .map(ToString::to_string)
+    .collect()
+}
+
 /// Get the filename for a library.
 ///
 /// `kind` should be one of:

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

@@ -64,6 +64,16 @@ test.
   - See [`support::compare`] for an explanation of the string pattern matching.
     Patterns are used to make it easier to match against the expected output.
 
+#### Filesystem layout testing
+
+Tests often to need to verify Cargo created/removed files.
+The `CargoPathExt` trait (implemented by `Path` and `PathBuf`) provides a `assert_dir_layout()` to verify the files in a directory (including nested directories).
+This takes a snapshot of file paths for the given directory and asserts that all files are present and no new files have been created.
+This function also takes a list of patterns to ignore from the snapshot to make working with platform specific files easier.
+
+Note: You will commonly need to call `unordered()` before passing your snapshot to deal with platform differences like binaries having `.exe` on Windows.
+`assert_build_dir_layout` is a more specialized version of `assert_dir_layout()` that is automatically unordered and ignores common platform specific files designed for the Cargo build cache.
+
 #### Testing Nightly Features
 
 If you are testing a Cargo feature that only works on "nightly" Cargo, then