Skip to content

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.md
index 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_sync
docs/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_sync
skills/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 URL
After 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 docs
4. **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.md
index 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.md
index 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") %}
&#32;&#32;<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, `🔥` urgent
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 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; fin
Finished 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.md
index 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 i
List all worktrees:
-<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__readme_example_list.snap — edit source to update -->
-
{% terminal(cmd="wt list") %}
&#32;&#32;<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") %}
&#32;&#32;<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") %}
&#32;&#32;<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.md
index 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 — no
Merge 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.md
index 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.md
index 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, r
Commit 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.rs
index 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.rs
index 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, Vec
Ok(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-matter
let 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"));