Add INSTA_PENDING_DIR environment variable for hermetic builds

[max-sixty]

Summary

This adds support for the INSTA_PENDING_DIR environment variable, which allows pending snapshots to be written to a separate directory while keeping the source tree read-only. This is particularly useful for hermetic build systems like Bazel.

When INSTA_PENDING_DIR is set:

• Pending snapshots (.snap.new and .pending-snap files) are written to the specified directory, preserving the same relative structure as the workspace
• cargo-insta correctly discovers and maps these pending snapshots back to their target locations in the source tree
• External test paths (e.g., path = "../tests/lib.rs") are rejected with a clear error, as they would escape the pending directory

Key changes

• insta: Add get_pending_dir() and pending_snapshot_path() in env.rs
• insta: Update runtime.rs to use pending_snapshot_path for all snapshot file operations
• insta: Create parent directories in snapshot.rs when pending dir is set
• cargo-insta: Update find_pending_snapshots() in walk.rs to support path mapping between pending_root and target_root
• cargo-insta: Simplify load_snapshot_containers() in cli.rs to use unified loop for both hermetic and default modes
• cargo-insta: Add comprehensive tests in pending_dir.rs (9 new tests)

Test plan

• All 93 cargo-insta tests pass
• New pending_dir tests cover: file snapshots, inline snapshots, accept, reject, auto-creation, update existing, check mode, outside workspace, and external test path rejection
• Clippy clean
• Pre-commit passes

🤖 Generated with Claude Code

[kormide]

I'm testing this on my Bazel example but running into a couple of issues:

1. Running tests under bazel with the following env vars, without sandboxed execution for simplicity:

env = {
    "INSTA_FORCE_PASS": "1",
    "INSTA_OUTPUT": "diff",
    "INSTA_UPDATE": "new",
    "INSTA_PENDING_DIR": "/".join(["$(RULEDIR)", "__{}_snapshots".format(name)]),
},

The value of INSTA_PENDING_DIR refers to some arbitrary location in the output tree for the .snap.new files to go.

I get the following error:

INSTA_PENDING_DIR is set but snapshot path "/home/derek/.cache/bazel/_bazel_derek/d2c61ba2af7a2993fb270be3e171b2ac/execroot/_main/src/snapshots/test__hello_world.snap" is outside workspace "/home/derek/.cache/bazel/_bazel_derek/d2c61ba2af7a2993fb270be3e171b2ac/execroot/_main". External test paths (e.g., path = "../tests/lib.rs" in Cargo.toml) are not compatible with INSTA_PENDING_DIR because the relative path would escape the pending directory.

Note that it detects /home/derek/.cache/bazel/_bazel_derek/d2c61ba2af7a2993fb270be3e171b2ac/execroot/_main as the workspace. The execroot is a tree of readonly symlinks that bazel creates mimicking the source tree and it's the directory where actions are run. This seems correct based on how I've laid out the test.

It detects /home/derek/.cache/bazel/_bazel_derek/d2c61ba2af7a2993fb270be3e171b2ac/execroot/_main/src/snapshots/test__hello_world.snap as incorrectly being outside of the workspace. My guess is that it's following symlinks back to the real source tree and detecting that as the root.

2. In an attempt to work around the above, I tried setting INSTA_WORKSPACE_ROOT to ".", hoping it will detect the execroot directory as the root. I get:

thread 'test_foo_bar' panicked at external/rules_rust++crate+crate_index__insta-1.45.1/src/env.rs:688:21: INSTA_PENDING_DIR is set but snapshot path "./src/snapshots/test__foo_bar.snap" is outside workspace ".". External test paths (e.g., path = "../tests/lib.rs" in Cargo.toml) are not compatible with INSTA_PENDING_DIR because the relative path would escape the pending directory.

3. Same as 2, but tried setting an empty string "" (not sure if this is valid in insta).

The .snap.new file is created, but it's created in the execroot symlink tree rather than in INSTA_PENDING_DIR, causing it to also appear in the real source tree (snapshot folder must also be a symlink). A build action writing files to the source tree wouldn't be idiomatic under Bazel, hence why we want to throw it in the output directory defined in INSTA_PENDING_DIR.

Let me know if I can clarify or test anything further.

[max-sixty]

@kormide have another look at the latest changes; I went back to using .canoncalize, and it seems to pass it the repro on bazel-examples at first glance (but am not confident)

I would need to fix for (non-bazel) Windows tests before merging; they seem to not like the symlinks...

[kormide]

@kormide have another look at the latest changes; I went back to using .canoncalize, and it seems to pass it the repro on bazel-examples at first glance (but am not confident)

I would need to fix for (non-bazel) Windows tests before merging; they seem to not like the symlinks...

I updated my example in aspect-build/bazel-examples#504 to use your changes and it works great! It also vastly simplified the implementation as I no longer have to rewrite paths or do any magic in the insta wrapper script for reviewing.

One nice-to-have would be a way to remove unreferenced snapshots using cargo insta review, as removing them during tests with --unreferenced wouldn't work under Bazel. I think this would mean that an unreferenced test would need to be somehow recorded in a new file output to the pending snapshot dir, e.g., test__foo_bar.snap.unreferenced. This is not critical though as the referenced snaps could be manually deleted.

I'm not sure about the Windows issues, but is it possible that symlinks aren't enabled on your Windows ci runner? IIRC symlinks are opt-in on Windows.

[max-sixty]

super!

I added the unreferenced issue as a TODO

I'll release this and let's see if there's more feedback on this working bazel, let's see how we do

thanks for suggesting & testing