Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(tests): consolidate three sync tests; drop dead inner snapshot wrappers (#2419)
Maximilian Roos66a5becc250f
diff --git a/CLAUDE.md b/CLAUDE.mdindex 14a33c005..73e463abd 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -118,7 +118,7 @@ Documentation has three categories:dev/*.example.toml (included via include_str!)↓src/cli/mod.rs (PRIMARY SOURCE)- ↓ test_command_pages_and_skill_files_are_in_sync+ ↓ test_docs_are_in_syncdocs/content/{command}.md → skills/worktrunk/reference/{command}.md```Edit `src/cli/mod.rs` (`after_long_help` attributes), never the docs directly.@@ -126,7 +126,7 @@ Documentation has three categories:2. **Non-command docs** (claude-code, faq, llm-commits, tips-patterns, worktrunk):```docs/content/*.md (PRIMARY SOURCE)- ↓ test_command_pages_and_skill_files_are_in_sync+ ↓ test_docs_are_in_syncskills/worktrunk/reference/*.md```Edit the docs file directly. Skill reference is auto-synced.@@ -151,7 +151,7 @@ Link text must stand alone when the URL is stripped (terminal help drops the URLAfter any doc changes, run tests to sync:```bash-cargo test --test integration test_command_pages_and_skill_files_are_in_sync+cargo test --test integration test_docs_are_in_sync```After editing `after_long_help` text, also update the help snapshots:@@ -423,7 +423,7 @@ CLI commands live in `src/cli/` with implementations in `src/commands/`.3. **Add `after_long_help`** attribute for extended help that syncs to docs4. **Run doc sync** after adding help text:```bash- cargo test --test integration test_command_pages_and_skill_files_are_in_sync+ cargo test --test integration test_docs_are_in_sync```Help text in `after_long_help` is the source of truth for `docs/content/{command}.md`.diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 43f9dedf1..33c459755 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -130,7 +130,7 @@ The generated content includes:After editing, run the sync test (which auto-updates out-of-sync pages):```bash-cargo test --test integration test_command_pages_and_skill_files_are_in_sync+cargo test --test integration test_docs_are_in_sync```### Command documentation structure@@ -216,7 +216,7 @@ This renders differently in each context:1. Edit test setup in `tests/integration_tests/list.rs` → `setup_readme_example_repo()`2. Run tests to regenerate snapshots: `cargo test --test integration readme_example_list`3. Accept snapshots: `cargo insta accept`-4. Sync docs: `cargo test --test integration test_command_pages_and_skill_files_are_in_sync`+4. Sync docs: `cargo test --test integration test_docs_are_in_sync`The examples in `cli.rs` are just command stubs — the actual output comes from snapshots generated by integration tests. This ensures docs always match real CLI behavior.diff --git a/docs/content/config.md b/docs/content/config.mdindex 3bef9f6d2..04b93f4df 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -966,8 +966,6 @@ Custom status text or emoji shown in the `wt list` Status column.Markers appear at the end of the Status column, after git symbols:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_marker.snap — edit source to update -->-{% terminal(cmd="wt list") %}  <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>@ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>@@ -978,8 +976,6 @@ Markers appear at the end of the Status column, after git symbols:<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead, 1 column hidden</span>{% end %}-<!-- END AUTO-GENERATED -->-### Use cases- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgentdiff --git a/docs/content/hook.md b/docs/content/hook.mdindex 1ac5923bc..f5a040747 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -251,8 +251,6 @@ copy = "wt step copy-ignored"The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__user_hooks__docs_hook_pre_merge.snap — edit source to update -->-{% terminal(cmd="wt hook pre-merge") %}<span class=c>◎</span> <span class=c>Running pre-merge <b>project:test</b></span><span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>cargo</span></span><span class=d> test</span>@@ -272,8 +270,6 @@ test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finFinished dev [unoptimized + debuginfo] target(s) in 1.23s{% end %}-<!-- END AUTO-GENERATED -->-{% terminal(cmd="wt hook post-start") %}◎ Running post-start: project @ ~/acme{% end %}diff --git a/docs/content/list.md b/docs/content/list.mdindex 5d0f358a9..5fd8f0fcc 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -30,8 +30,6 @@ The table renders progressively: branch names, paths, and commit hashes appear iList all worktrees:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->-{% terminal(cmd="wt list") %}  <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>6814f02a</span> <span class=d>30m</span> <span class=d>Add API tests</span>@@ -42,12 +40,8 @@ List all worktrees:<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden</span>{% end %}-<!-- END AUTO-GENERATED -->-Include CI status, line diffs, and LLM summaries:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_full.snap — edit source to update -->-{% terminal(cmd="wt list --full") %}  <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>@@ -58,12 +52,8 @@ Include CI status, line diffs, and LLM summaries:<span class=d>○</span> <span class=d>Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden</span>{% end %}-<!-- END AUTO-GENERATED -->-Include branches that don't have worktrees:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list_branches.snap — edit source to update -->-{% terminal(cmd="wt list --branches --full") %}  <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>main…±</b> <b>Summary</b> <b>Remote⇅</b> <b>CI</b> <b>Commit</b>@ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>+234</span> <span class=r>-24</span> Refactor API to REST architecture with middleware <span class=g>⇡3</span> <span class=d><span style='color:var(--blue,#00a)'>●</span></span> <span class=d>6814f02a</span>@@ -76,8 +66,6 @@ Include branches that don't have worktrees:<span class=d>○</span> <span class=d>Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden</span>{% end %}-<!-- END AUTO-GENERATED -->-Output as JSON for scripting:{{ terminal(cmd="wt list --format=json") }}diff --git a/docs/content/merge.md b/docs/content/merge.mdindex 923fc5441..cab80e297 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -24,8 +24,6 @@ Unlike `git merge`, this merges the current branch into the target branch — noMerge to the default branch:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_merge_pre_merge_hook.snap — edit source to update -->-{% terminal(cmd="wt merge") %}<span class=c>◎</span> <span class=c>Running pre-merge <b>project:test</b></span><span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>cargo</span></span><span class=d> nextest run</span>@@ -40,8 +38,6 @@ Merge to the default branch:<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>~/repo</b>{% end %}-<!-- END AUTO-GENERATED -->-Merge to a different branch:{{ terminal(cmd="wt merge develop") }}diff --git a/docs/content/remove.md b/docs/content/remove.mdindex 6236df3ab..f8727e8dc 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -15,8 +15,6 @@ Remove worktree; delete branch if merged. Defaults to the current worktree.Remove current worktree:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__remove__docs_remove_pre_remove_hook.snap — edit source to update -->-{% terminal(cmd="wt remove") %}<span class=c>◎</span> <span class=c>Running pre-remove <b>project:cleanup</b></span><span style='background:var(--bright-white,#fff)'> </span> <span class=d><span style='color:var(--blue,#00a)'>flyctl</span></span><span class=d> scale count 0</span>@@ -25,8 +23,6 @@ Scaling app to 0 machines<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>~/repo</b>{% end %}-<!-- END AUTO-GENERATED -->-Remove specific worktrees / branches:{{ terminal(cmd="wt remove feature-branch|||wt remove old-feature another-branch") }}diff --git a/docs/content/step.md b/docs/content/step.mdindex aaafaa890..216045b44 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -15,16 +15,12 @@ Run individual operations. The building blocks of wt merge — commit, squash, rCommit with LLM-generated message:-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap — edit source to update -->-{% terminal(cmd="wt step commit") %}<span class=c>◎</span> <span class=c>Generating commit message and committing changes... <span style='color:var(--bright-black,#555)'>(2 files, <span class=g>+26</span></span></span><span style='color:var(--bright-black,#555)'>)</span><span style='background:var(--bright-white,#fff)'> </span> <b>feat(validation): add input validation utilities</b><span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>{% end %}-<!-- END AUTO-GENERATED -->-Manual merge workflow with review between steps:{{ terminal(cmd="wt step commit|||wt step squash|||wt step rebase|||wt step push") }}diff --git a/src/help.rs b/src/help.rsindex b0ff22936..578a85131 100644--- a/src/help.rs+++ b/src/help.rs@@ -130,7 +130,8 @@ impl PageMode {}/// Emit the closing END marker (web only). Mirrors the open id so the sync- /// test can pair adjacent regions unambiguously.+ /// test can disambiguate from inner snapshot-marker closes nested inside+ /// the help-page region.fn emit_footer(self, subcommand: &str) {if matches!(self, Self::Web) {std::println!();diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex c23124dbc..8c0ba184a 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -500,11 +500,12 @@ fn expand_command_placeholders(// placeholder id, so disambiguation suffixes like `(markers)`// don't leak into the rendered prompt. Prompt ($) is added// via CSS ::before, so not included in HTML.- wrap_in_marker(- &format!("tests/snapshots/{snapshot_name}"),- "source",- &format!("{{% terminal(cmd=\"{display_cmd}\") %}}\n{normalized}\n{{% end %}}",),- )+ //+ // No inner AUTO-GENERATED wrapper — the whole command page+ // regenerates wholesale each sync, so the wrapper is dead+ // weight and would nest inside the outer help-page region's+ // markers (forcing the outer regex to use a tempered match).+ format!("{{% terminal(cmd=\"{display_cmd}\") %}}\n{normalized}\n{{% end %}}")}ExpandMode::Plain => {let plain = trim_lines(&parse_snapshot_content_for_skill(&snapshot_content));@@ -1588,38 +1589,6 @@ fn sync_help_markers(file_path: &Path, project_root: &Path) -> Result<usize, VecOk(updated)}-#[test]-fn test_readme_examples_are_in_sync() {- let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));- let readme_path = project_root.join("README.md");-- let readme_content = fs::read_to_string(&readme_path).unwrap();-- // Single pass handles all marker types (snapshots, help, sections)- match sync_readme_markers(&readme_content, project_root) {- Ok((updated_content, updated_count, total_count)) => {- if total_count == 0 {- panic!("No README markers found in README.md");- }-- if updated_count > 0 {- fs::write(&readme_path, &updated_content).unwrap();- panic!(- "README out of sync: updated {} of {} section(s). \- Run tests locally and commit the changes.",- updated_count, total_count- );- }- }- Err(errors) => {- panic!(- "README examples are out of sync:\n\n{}\n",- errors.join("\n")- );- }- }-}-#[test]fn test_docs_commands_are_in_sync() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));@@ -1690,45 +1659,6 @@ fn sync_docs_snapshots(doc_path: &Path, project_root: &Path) -> Result<usize, Ve}}-#[test]-fn test_docs_quickstart_examples_are_in_sync() {- let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));-- // Process all docs files with snapshot-driven AUTO-GENERATED markers- let doc_files = [- "docs/content/worktrunk.md",- "docs/content/claude-code.md",- "docs/content/tips-patterns.md",- "docs/content/llm-commits.md",- ];-- let mut all_errors = Vec::new();- let mut total_updated = 0;-- for doc_file in doc_files {- let doc_path = project_root.join(doc_file);- match sync_docs_snapshots(&doc_path, project_root) {- Ok(updated) => total_updated += updated,- Err(errors) => all_errors.extend(errors),- }- }-- if !all_errors.is_empty() {- panic!(- "Docs examples are out of sync:\n\n{}\n",- all_errors.join("\n")- );- }-- if total_updated > 0 {- panic!(- "Docs examples out of sync: updated {} section(s). \- Run tests locally and commit the changes.",- total_updated- );- }-}-/// Update or insert the `description` field in TOML frontmatter.////// Handles three cases:@@ -1884,10 +1814,11 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {current.clone()};- // Find the help-page marker region. The help-page emitter uses a- // mirrored close (`<!-- END AUTO-GENERATED from <id> -->`) so that- // adjacent regions never need backtracking past the wrong one — match- // the same id literally on both sides.+ // Find the help-page marker region. The mirrored close+ // (`<!-- END AUTO-GENERATED from <id> -->`) is required because the+ // help-page body can contain inner snapshot markers (which use the+ // bare `MARKER_CLOSE`); a bare close on the outer region would let+ // the regex stop at the first inner close.let id_re = regex::escape(&format!("`wt {cmd} --help-page`"));let marker_pattern = Regex::new(&format!(r"(?s){open}{id_re}[^>]*-->.*?<!-- END AUTO-GENERATED from {id_re} -->",@@ -2608,50 +2539,96 @@ fn extract_intro_prose(body: &str) -> String {lines.join("\n").trim().to_string()}-/// Combined test: sync command pages (mod.rs → docs) then skill files (docs → skills)-/// then .well-known/agent-skills/ (skills → docs/static) then llms.txt.-/// This ensures a single test run handles the full chain when mod.rs changes.+/// Single end-to-end sync test that owns the full pipeline.+///+/// Steps run in dependency order, so a single pass converges and there's no+/// way for nextest parallelism to interleave the stages. The earlier+/// per-stage tests (`test_docs_quickstart_examples_are_in_sync`,+/// `test_readme_examples_are_in_sync`) collapsed into this — they shared+/// state via on-disk docs files, which made test ordering a correctness+/// requirement, not a performance choice.#[test]-fn test_command_pages_and_skill_files_are_in_sync() {+fn test_docs_are_in_sync() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));+ // Each step's errors and updated-file list are tagged so the failure+ // message tells a developer which stage broke without grepping for code.+ let mut all_errors: Vec<String> = Vec::new();+ let mut all_files: Vec<String> = Vec::new();+ let mut tag = |stage: &str, errors: Vec<String>, files: Vec<String>| {+ all_errors.extend(errors.into_iter().map(|e| format!("[{stage}] {e}")));+ all_files.extend(files.into_iter().map(|f| format!("[{stage}] {f}")));+ };+// Step 0: Fill docs-example bodies in src/cli/mod.rs from snapshots. Runs// before --help-page reads the file so command pages and skill files see// the up-to-date content.let (mod_errors, mod_files) = sync_cli_mod_example_bodies(project_root);+ tag("cli/mod.rs", mod_errors, mod_files);// Step 1: Sync command pages (mod.rs → docs/content/*.md)let (cmd_errors, cmd_files) = sync_command_pages(project_root);+ tag("command pages", cmd_errors, cmd_files);// Step 1b: Convert $ console blocks to terminal shortcodes in ALL docs// (command pages already converted via --help-page; this catches hand-written docs)let console_files = convert_console_blocks_in_docs(project_root);+ tag("console→terminal", Vec::new(), console_files);++ // Step 2: Sync standalone docs files (snapshots → docs/content/*.md).+ // README extraction in step 5 reads these, so they must be current first.+ let standalone_doc_files = [+ "docs/content/worktrunk.md",+ "docs/content/claude-code.md",+ "docs/content/tips-patterns.md",+ "docs/content/llm-commits.md",+ ];+ let mut docs_errors: Vec<String> = Vec::new();+ let mut docs_files: Vec<String> = Vec::new();+ for doc_file in standalone_doc_files {+ let doc_path = project_root.join(doc_file);+ match sync_docs_snapshots(&doc_path, project_root) {+ Ok(updated) => {+ if updated > 0 {+ docs_files.push(doc_file.to_string());+ }+ }+ Err(errors) => docs_errors.extend(errors),+ }+ }+ tag("standalone docs", docs_errors, docs_files);- // Step 2: Sync skill files (docs/content/*.md → skills/*)- // This reads the freshly-written docs from step 1+ // Step 3: Sync skill files (docs/content/*.md → skills/*)let (skill_errors, skill_files) = sync_skill_files(project_root);+ tag("skill files", skill_errors, skill_files);- // Step 3: Sync .well-known/agent-skills/ (skills/ → docs/static/)- // This reads the freshly-written skills from step 2+ // Step 4: Sync .well-known/agent-skills/ (skills/ → docs/static/)let well_known_files = sync_well_known_skills(project_root);+ tag(".well-known", Vec::new(), well_known_files);- // Step 4: Generate docs/static/llms.txt from docs/content front-matter+ // Step 5: Generate docs/static/llms.txt from docs/content front-matterlet llms_files = sync_llms_txt(project_root);+ tag("llms.txt", Vec::new(), llms_files);- // Aggregate results- let all_errors: Vec<_> = mod_errors- .into_iter()- .chain(cmd_errors)- .chain(skill_errors)- .collect();- let all_files: Vec<_> = mod_files- .into_iter()- .chain(cmd_files)- .chain(console_files)- .chain(skill_files)- .chain(well_known_files)- .chain(llms_files)- .collect();+ // Step 6: Sync README from the now-fresh docs files. Runs last because+ // section extraction depends on docs/content/*.md being current.+ let readme_path = project_root.join("README.md");+ let readme_content = fs::read_to_string(&readme_path).unwrap();+ let mut readme_errors: Vec<String> = Vec::new();+ let mut readme_files: Vec<String> = Vec::new();+ match sync_readme_markers(&readme_content, project_root) {+ Ok((updated_content, updated_count, total_count)) => {+ assert!(total_count > 0, "No README markers found in README.md");+ if updated_count > 0 {+ fs::write(&readme_path, &updated_content).unwrap();+ readme_files.push(format!(+ "README.md ({updated_count} of {total_count} section(s) updated)"+ ));+ }+ }+ Err(errors) => readme_errors.extend(errors),+ }+ tag("README", readme_errors, readme_files);if !all_errors.is_empty() {panic!("Sync errors:\n\n{}\n", all_errors.join("\n"));