Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Guard tests over the committed snapshot corpus.
//!
//! Snapshots capture real output and are approved by reviewers. Subtle
//! problems slip through review: formatting issues (stray blank lines,
//! detached hints), and host-specific paths that insta never compares.
//! These tests scan every committed `.snap` file to enforce the rules.
//!
//! Rules enforced:
//! - **Hints attach to their subject** — no blank line before `↳`
//! - **No double blank lines** — one blank line maximum between elements
//! - **No host-specific paths** — insta compares only snapshot *content*
//! (stdout/stderr/exit code); the `info:` block insta-cmd records
//! (`args:`, `env:`) is metadata that is written but never compared, and
//! `add_filter` doesn't apply to it. A test missing a redaction therefore
//! bakes the generating machine's paths into the committed file while
//! passing everywhere — surfacing only as churn when someone regenerates
//! the snapshot on another machine (and under libtest, the `repo`
//! fixture's leaked settings binding can mask the omission; see `repo()`
//! in `tests/common`). This rule makes the leak fail deterministically.
//!
//! When a formatting rule fails:
//! 1. Fix the source code producing the bad output
//! 2. Re-run the failing test to regenerate the snapshot
//! 3. If the blank line is intentional (e.g., phase boundary before a status
//! item that uses `↳`), add the snapshot to the allowlist with a comment
//!
//! When the host-path rule fails: add a redaction — env values go in
//! `add_standard_env_redactions`, path arguments are covered by the
//! `.args[]` redaction in `add_repo_and_worktree_path_filters` (both in
//! `tests/common/mod.rs`); see tests/AGENTS.md "Snapshot env drift".
use crate::common::source_scan::visit_files;
use ansi_str::AnsiStr;
use regex::Regex;
use std::path::Path;
use std::sync::LazyLock;
/// Snapshots where a blank line before `↳` is intentional (phase boundary, not
/// a detached hint). Each entry needs a comment explaining why.
const BLANK_BEFORE_HINT_ALLOWED: &[&str] = &[
// config show: blank line separates "Shell integration not active" diagnostic
// from per-shell status section. The `↳` here is a status item, not a hint.
"config_show__config_show_partial_shell_config_shows_hint",
"config_show__config_show_unmatched_candidate_warning",
"config_show__config_show_unmatched_candidate_not_suppressed_by_wrapper",
];
#[test]
fn test_no_blank_line_before_hint_in_snapshots() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
let mut violations = Vec::new();
for_each_snapshot(project_root, |path, content| {
let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("");
if BLANK_BEFORE_HINT_ALLOWED
.iter()
.any(|allowed| stem.contains(allowed))
{
return;
}
let clean = content.ansi_strip();
let lines: Vec<&str> = clean.lines().collect();
for (i, line) in lines.iter().enumerate() {
if line.trim().starts_with('↳') && i > 0 && lines[i - 1].trim().is_empty() {
let relative = path.strip_prefix(project_root).unwrap_or(path);
violations.push(format!(
"{}:{}: blank line before hint\n {}: {:?}\n {}: {:?}",
relative.display(),
i + 1,
i,
lines[i - 1],
i + 1,
line,
));
}
}
});
if !violations.is_empty() {
panic!(
"Blank line before hint (↳) in {} snapshot(s):\n\n{}\n\n\
Hints attach to their subject — no blank line between a message and its hint.\n\
Fix the source code, not the snapshot. If the blank line is intentional,\n\
add the snapshot to BLANK_BEFORE_HINT_ALLOWED with a comment.",
violations.len(),
violations.join("\n\n"),
);
}
}
#[test]
fn test_no_double_blank_lines_in_snapshot_output() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
let mut violations = Vec::new();
for_each_snapshot(project_root, |path, content| {
// Extract output content, skipping YAML header.
// Two formats: stdout/stderr sections (insta_cmd) or expression
// content after closing `---`.
for (label, text) in extract_output_sections(content) {
let clean = text.ansi_strip();
if clean.contains("\n\n\n") {
let relative = path.strip_prefix(project_root).unwrap_or(path);
violations.push(format!("{} ({label})", relative.display()));
}
}
});
if !violations.is_empty() {
panic!(
"Double blank lines in {} snapshot output section(s):\n\n{}\n\n\
One blank line maximum between output elements.",
violations.len(),
violations.join("\n"),
);
}
}
/// Markers that only ever come from the generating machine: macOS per-user
/// temp dirs, the LLVM profile fallback dir (always under the host temp
/// dir), and tempfile's random `.tmpXXXXXX` directories.
static HOST_MARKERS: LazyLock<[Regex; 3]> = LazyLock::new(|| {
[
Regex::new(r"/var/folders/").unwrap(),
Regex::new(r"wt-test-profraw").unwrap(),
Regex::new(r"\.tmp[A-Za-z0-9]{6}").unwrap(),
]
});
/// Home-style paths are allowed only for the deliberate fake users in docs
/// examples and mocked output; a real username means an unredacted $HOME
/// leaked. `{1,2}` separators: YAML double-quoted scalars escape
/// backslashes, so a Windows path arrives as `C:\\Users\\name`.
static HOME_PATH: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"[/\\]{1,2}(?:Users|home)[/\\]{1,2}([A-Za-z0-9._-]+)").unwrap());
const FAKE_USERS: &[&str] = &["me", "user"];
fn line_has_host_specific_path(line: &str) -> bool {
HOST_MARKERS.iter().any(|re| re.is_match(line))
|| HOME_PATH
.captures_iter(line)
.any(|c| !FAKE_USERS.contains(&&c[1]))
}
#[test]
fn test_no_host_specific_paths_in_snapshots() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
let mut violations = Vec::new();
for_each_snapshot(project_root, |path, content| {
for (i, line) in content.lines().enumerate() {
if line_has_host_specific_path(line) {
let relative = path.strip_prefix(project_root).unwrap_or(path);
violations.push(format!("{}:{}: {}", relative.display(), i + 1, line.trim()));
}
}
});
if !violations.is_empty() {
panic!(
"Host-specific paths in {} committed snapshot line(s):\n\n{}\n\n\
These churn whenever the snapshot is regenerated on another machine.\n\
Add a redaction: env values in `add_standard_env_redactions`, path\n\
arguments via the `.args[]` redaction in `add_repo_and_worktree_path_filters`\n\
(tests/common/mod.rs); see tests/AGENTS.md \"Snapshot env drift\".\n\
Deliberate example paths use the fake users in FAKE_USERS.",
violations.len(),
violations.join("\n"),
);
}
}
/// Visit every committed `.snap` file. Snapshot dirs live under `src`
/// (unit tests), `tests` (integration tests), and `docs` (demo fixtures).
fn for_each_snapshot(project_root: &Path, mut f: impl FnMut(&Path, &str)) {
// Per root rather than in aggregate: `tests` alone holds the large majority
// of the corpus, so a total count survives that root moving away. Each root
// is load-bearing as a result — one that legitimately stops holding
// snapshots belongs out of this list, not exempted from it.
for root in ["src", "tests", "docs"] {
let seen = visit_files(&project_root.join(root), "snap", "snapshot scan", &mut f);
assert!(
seen > 0,
"{root}/ holds no .snap files — the corpus has moved, so these \
assertions are now passing over whatever is left of it"
);
}
}
/// Extract labeled output sections from a snapshot file.
///
/// Handles two formats:
/// - **insta_cmd**: sections delimited by `----- stdout -----` / `----- stderr -----`
/// - **expression**: content after the closing `---` YAML delimiter
fn extract_output_sections(content: &str) -> Vec<(&str, &str)> {
let mut sections = Vec::new();
// Try stdout/stderr sections (insta_cmd format)
for section in ["stdout", "stderr"] {
let marker = format!("----- {section} -----");
let Some(start) = content.find(&marker) else {
continue;
};
let after_marker = &content[start + marker.len()..];
let end = after_marker
.find("----- stdout -----")
.or_else(|| after_marker.find("----- stderr -----"))
.unwrap_or(after_marker.len());
sections.push((section, &after_marker[..end]));
}
// If no stdout/stderr sections, try expression format (content after closing ---)
// Match `---` only at line boundaries to avoid false matches on content like
// `--- a/file.txt` in git diffs.
if sections.is_empty() {
let first_delim = if content.starts_with("---\n") {
Some(0)
} else {
content.find("\n---\n").map(|pos| pos + 1)
};
if let Some(pos) = first_delim {
let after_first = &content[pos + 3..];
if let Some(nl_pos) = after_first.find("\n---\n") {
let output = &after_first[nl_pos + 4..];
sections.push(("expression", output));
}
}
}
sections
}
#[cfg(test)]
mod tests {
use super::*;
/// The corpus test passes vacuously if the detector rots — pin its
/// sensitivity on both sides. Leak lines are the shapes actually found
/// in committed snapshots (#3009 and the `args:` leak this fixed).
#[test]
fn test_host_specific_path_detection() {
let leaks = [
// macOS per-user temp dir (env value, the #3009 class)
"LLVM_PROFILE_FILE: /var/folders/v3/8k5q0_6j3/T/wt-test-profraw/cov.profraw",
// tempfile-crate dir in the args: block
"- /private/var/folders/wf/s6ycxvvs/T/.tmpSeGxzx/repo",
// tempfile-crate dir under /tmp (Linux)
"path: /tmp/.tmpAbC123/repo",
// real home dirs, Unix and YAML-escaped Windows
"HOME: /Users/maximilian/workspace",
"HOME: /home/runner/work",
r#"USERPROFILE: "C:\\Users\\runneradmin\\AppData""#,
];
for line in leaks {
assert!(line_has_host_specific_path(line), "should flag: {line}");
}
let deterministic = [
// deliberate fake users in docs examples and mocked output
"e.g., /Users/me/code/myproject",
"To /Users/user/workspace/repo/.git",
r#"PSModulePath: "C:\\Users\\user\\Documents""#,
// machine-independent literals and placeholders
"WORKTRUNK_CONFIG_PATH: /nonexistent/wt/config.toml",
"LLVM_PROFILE_FILE: \"[LLVM_PROFILE_FILE]\"",
"WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml",
];
for line in deterministic {
assert!(!line_has_host_specific_path(line), "should allow: {line}");
}
}
#[test]
fn test_extract_output_sections_ignores_mid_line_dashes() {
// Simulate a snapshot whose output body contains `--- a/file.txt` (git diff).
// The old code matched `---` as a bare substring and would split incorrectly.
let content = "\
---
source: tests/some_test.rs
expression: output
---
diff --git a/file.txt b/file.txt
--- a/file.txt
+++ b/file.txt
@@ -1 +1 @@
-old
+new
";
let sections = extract_output_sections(content);
assert_eq!(sections.len(), 1);
assert_eq!(sections[0].0, "expression");
assert!(
sections[0].1.contains("--- a/file.txt"),
"mid-line `---` should be part of the output, not a delimiter"
);
}
#[test]
fn test_extract_output_sections_expression_format() {
let content = "\
---
source: tests/some_test.rs
expression: output
---
hello world
";
let sections = extract_output_sections(content);
assert_eq!(sections.len(), 1);
assert_eq!(sections[0].0, "expression");
assert_eq!(sections[0].1.trim(), "hello world");
}
}