Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(demos): add snapshot mode for regression testing (#871)
Maximilian Roos47ec8838d44c
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.mdindex 7db42963c..606903bbc 100644--- a/docs/demos/CLAUDE.md+++ b/docs/demos/CLAUDE.md@@ -43,6 +43,33 @@ Regenerate a single demo:| docs | wt-core, wt-switch, wt-list, wt-commit, wt-statusline, wt-merge, wt-select, wt-zellij-omnibus || social | wt-switch, wt-statusline, wt-list, wt-list-remove, wt-hooks, wt-devserver, wt-commit, wt-merge, wt-select, wt-core, wt-zellij-omnibus |+## Snapshot testing++```bash+./docs/demos/build docs --snapshot # Generate all snapshots+./docs/demos/build docs --snapshot --only wt-list # Single demo+```++Snapshots capture command output (not terminal rendering) and are committed to `docs/demos/snapshots/`. Use them to catch regressions like new hints creeping in.++**How to use:**+1. After changing wt output, regenerate snapshots: `./docs/demos/build docs --snapshot`+2. Review the diff - small changes (commit hashes, minor formatting) are expected+3. Commit the updated snapshots alongside your changes++**What changes are expected:**+- Commit hashes change each run (demo repo is recreated)+- Column widths may shift slightly++**What changes indicate regressions:**+- New hints or warnings appearing+- Output format changes you didn't intend+- New lines or missing output++**Limitations:**+- Tab completion sequences are not replayed; only `Type "command"` + `Enter` patterns are extracted+- TUI demos (wt-select, wt-switch, wt-statusline, wt-zellij-omnibus) are skipped since they require interactive input+## Prerequisites**Requires Go** — The VHS fork is built from source ([install Go](https://go.dev/dl/)).diff --git a/docs/demos/build b/docs/demos/buildindex 8e88cd446..9fbc7e26c 100755--- a/docs/demos/build+++ b/docs/demos/build@@ -43,6 +43,7 @@ from shared import ( # noqa: E402SIZE_DOCS,SIZE_SOCIAL,record_text,+ record_snapshot,build_tape_replacements,ensure_vhs_binary,)@@ -50,6 +51,10 @@ from shared import ( # noqa: E402REPO_ROOT = SCRIPT_DIR.parent.parentOUT_DIR = SCRIPT_DIR.parent / "static" / "assets"TAPES_DIR = SCRIPT_DIR / "tapes"+SNAPSHOTS_DIR = SCRIPT_DIR / "snapshots"++# Demos that use TUI or interactive input - not suitable for command snapshots+TUI_DEMOS = {"wt-select", "wt-switch", "wt-statusline", "wt-zellij-omnibus"}# =============================================================================@@ -342,6 +347,7 @@ def record_demo(demo_size: DemoSize,vhs_binary: str,text_mode: bool = False,+ snapshot_mode: bool = False,):"""Record a single demo (runs in subprocess for parallel execution)."""tape_path = TAPES_DIR / tape_file@@ -356,7 +362,11 @@ def record_demo(replacements = build_tape_replacements(env, REPO_ROOT)- if text_mode:+ if snapshot_mode:+ output_snap = SNAPSHOTS_DIR / f"{output_name}.snap"+ record_snapshot(env, tape_path, output_snap, REPO_ROOT)+ print(f"✓ {output_name}: Snapshot saved to {output_snap}")+ elif text_mode:output_txt = mode_out_dir / f"{output_name}.txt"record_text(env, tape_path, output_txt, replacements, REPO_ROOT)print(f"✓ {output_name}: Text saved to {output_txt}")@@ -431,6 +441,11 @@ Examples:parser.add_argument("--text", action="store_true", help="Record text output instead of GIFs")+ parser.add_argument(+ "--snapshot",+ action="store_true",+ help="Record command output snapshots for regression testing (non-TUI demos only)",+ )parser.add_argument("--sequential",action="store_true",@@ -446,6 +461,14 @@ Examples:print("--shell and --text are mutually exclusive")return+ if args.shell and args.snapshot:+ print("--shell and --snapshot are mutually exclusive")+ return++ if args.text and args.snapshot:+ print("--text and --snapshot are mutually exclusive")+ return+# Check dependencies (VHS is built from source, not required in PATH)deps = ["wt", "starship", "zellij"]check_dependencies(deps)@@ -475,6 +498,17 @@ Examples:print(f"Available for {args.target}: {', '.join(all_names)}")return+ # Filter out TUI demos in snapshot mode+ if args.snapshot:+ original_count = len(demos)+ demos = [(t, n, s) for t, n, s in demos if n not in TUI_DEMOS]+ skipped = original_count - len(demos)+ if skipped:+ print(f"Skipping {skipped} TUI demo(s) (not snapshotable)")+ if not demos:+ print("No snapshotable demos found")+ return+# Handle --shell mode (interactive, must be sequential)if args.shell:tape_file, output_name, setup_func = demos[0]@@ -501,6 +535,7 @@ Examples:demo_size,vhs_binary,args.text,+ args.snapshot,)except Exception as e:print(f"✗ {output_name}: {e}")@@ -521,6 +556,7 @@ Examples:demo_size,vhs_binary,args.text,+ args.snapshot,): output_namefor tape_file, output_name, setup_func in demos}diff --git a/docs/demos/shared/__init__.py b/docs/demos/shared/__init__.pyindex a4e1c3937..dde40339b 100644--- a/docs/demos/shared/__init__.py+++ b/docs/demos/shared/__init__.py@@ -27,6 +27,9 @@ from .lib import (# Text output recordingrecord_text,build_tape_replacements,+ # Snapshot recording+ extract_commands_from_tape,+ record_snapshot,# External dependenciesensure_vhs_binary,)@@ -61,6 +64,9 @@ __all__ = [# Text output recording"record_text","build_tape_replacements",+ # Snapshot recording+ "extract_commands_from_tape",+ "record_snapshot",# External dependencies"ensure_vhs_binary",]diff --git a/docs/demos/shared/lib.py b/docs/demos/shared/lib.pyindex 39fa744b3..1ad582cad 100644--- a/docs/demos/shared/lib.py+++ b/docs/demos/shared/lib.py@@ -936,6 +936,163 @@ def record_text(temp_txt.unlink()+def extract_commands_from_tape(+ tape_path: Path, repo_root: Path, command_prefixes: tuple[str, ...] = ("wt", "git")+) -> list[str]:+ """Extract shell commands from a VHS tape file.++ Parses the tape looking for Type "command" followed by Enter patterns,+ filtering to commands that start with specified prefixes (default: wt, git).++ Only extracts commands after Show directive (visible part of demo).+ Skips commands in Hide blocks.++ Args:+ tape_path: Path to the .tape template file+ repo_root: Root of the repository (for resolving Source paths)+ command_prefixes: Tuple of command prefixes to extract (default: wt, git)++ Returns:+ List of commands in order they appear in the tape+ """+ # Render tape with dummy replacements to inline Source directives+ rendered = render_tape(tape_path, {}, repo_root)+ if not rendered:+ return []++ commands = []+ in_visible_section = False+ lines = rendered.split("\n")+ i = 0++ while i < len(lines):+ line = lines[i].strip()++ # Track visibility+ if line == "Show":+ in_visible_section = True+ elif line == "Hide":+ in_visible_section = False++ # Look for Type "command" pattern+ if in_visible_section and line.startswith("Type "):+ # Extract command from Type "..." or Type '...'+ match = re.match(r'Type\s+["\'](.+)["\']', line)+ if match:+ cmd = match.group(1)+ # Check if Enter follows (possibly with Sleep in between)+ j = i + 1+ while j < len(lines):+ next_line = lines[j].strip()+ if not next_line:+ j += 1+ continue+ if next_line.startswith("Sleep "):+ j += 1+ continue+ if next_line == "Enter":+ # Only include commands with specified prefixes+ if any(cmd.startswith(prefix) for prefix in command_prefixes):+ commands.append(cmd)+ break+ i += 1++ return commands+++def record_snapshot(+ demo_env: "DemoEnv",+ tape_path: Path,+ output_snap: Path,+ repo_root: Path,+) -> None:+ """Record command output snapshot for regression testing.++ Extracts commands from the tape and runs them in a fish shell with full+ shell integration (just like the GIF demos). The snapshot format is:++ $ wt list+ <output>++ $ wt switch alpha+ <output>++ This captures semantic output (what commands produce) rather than visual+ rendering (how it looks in a terminal). Small diffs are expected when+ output formats change; the goal is catching unexpected regressions like+ new hints or warnings creeping in.++ Args:+ demo_env: Demo environment with repo and home paths+ tape_path: Path to the .tape template file+ output_snap: Path to write snapshot output+ repo_root: Root of the repository++ Raises:+ RuntimeError: If no commands found in tape+ """+ commands = extract_commands_from_tape(tape_path, repo_root)+ if not commands:+ raise RuntimeError(f"No snapshotable commands found in {tape_path.name}")++ # Build environment matching the GIF demos+ env = os.environ.copy()+ env.update(+ {+ "HOME": str(demo_env.home),+ "XDG_CONFIG_HOME": str(demo_env.home / ".config"),+ "PATH": f"{repo_root / 'target' / 'debug'}:{demo_env.home / '.local' / 'bin'}:{os.environ.get('PATH', '')}",+ "TERM": "xterm-256color",+ "LANG": "en_US.UTF-8",+ "LC_ALL": "en_US.UTF-8",+ }+ )++ # Generate a fish script that:+ # 1. Initializes shell integration (like shared-commands.tape)+ # 2. Runs each command, printing "$ cmd" before and blank line after+ script_lines = [+ "# Initialize shell integration",+ "wt config shell init fish | source",+ "source ~/.config/fish/completions/wt.fish",+ f"cd {demo_env.repo}",+ "",+ ]++ for i, cmd in enumerate(commands):+ # Echo the command prompt, run command (merging stderr)+ script_lines.append(f"echo '$ {cmd}'")+ script_lines.append(f"{cmd} 2>&1")+ # Blank line between commands (not after last)+ if i < len(commands) - 1:+ script_lines.append("echo ''")++ script_content = "\n".join(script_lines)+ script_path = demo_env.out_dir / ".snapshot-script.fish"+ script_path.write_text(script_content)++ # Run the script in fish+ result = subprocess.run(+ ["fish", str(script_path)],+ env=env,+ capture_output=True,+ text=True,+ )++ # Combine stdout and stderr+ output = (result.stdout + result.stderr).rstrip()++ # Normalize temp paths to stable placeholder+ temp_path = str(demo_env.out_dir)+ temp_path_real = str(demo_env.out_dir.resolve())+ output = output.replace(temp_path_real, "<DEMO_DIR>")+ output = output.replace(temp_path, "<DEMO_DIR>")++ # Write snapshot+ output_snap.parent.mkdir(parents=True, exist_ok=True)+ output_snap.write_text(output + "\n")++@dataclassclass DemoSize:"""Canvas and font size for demo recording."""diff --git a/docs/demos/snapshots/wt-commit.snap b/docs/demos/snapshots/wt-commit.snapnew file mode 100644index 000000000..de6c46f2c--- /dev/null+++ b/docs/demos/snapshots/wt-commit.snap@@ -0,0 +1,26 @@+$ wt switch hooks+○ Switched to worktree for hooks @ <DEMO_DIR>/.demo-wt-commit/w/acme.hooks+[0m+$ git diff --staged --stat+ src/lib.rs | 1 ++ src/validation.rs | 23 ++++++++++++++++++++++++ 2 files changed, 24 insertions(+)++$ wt step commit+◎ Generating commit message and committing changes... (2 files, +25)+ feat(validation): add input validation utilities++ Add validation module with is_positive and is_non_empty helpers+ for validating user input. Includes comprehensive test coverage.+✓ Committed changes @ 200f6f2+[0m+$ git log -1+commit 200f6f2d9731f93626892c1a410f942217189339+Author: Worktrunk Demo <[email protected]>+Date: Mon Jan 26 13:27:07 2026 -0800++ feat(validation): add input validation utilities++ Add validation module with is_positive and is_non_empty helpers+ for validating user input. Includes comprehensive test coverage.+[0mdiff --git a/docs/demos/snapshots/wt-core.snap b/docs/demos/snapshots/wt-core.snapnew file mode 100644index 000000000..bf5006924--- /dev/null+++ b/docs/demos/snapshots/wt-core.snap@@ -0,0 +1,35 @@+$ wt list+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add developm…[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+2[0m [32m↑1[0m [2m0967fab5[0m [2m2h[0m [2mfeat: add math ope…[0m++ [2mbilling[0m [2m_[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add developm…[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m⇡1[0m [2mf31634d7[0m [2m3d[0m [2mdocs: add FAQ sect…[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2mb10e3edd[0m [2m5d[0m [2mAdd project hooks[0m++[2m○[22m [2mShowing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden[0m+[0m+$ wt switch alpha+○ Switched to worktree for alpha @ <DEMO_DIR>/.demo-wt-core/w/acme.alpha+[0m+$ wt switch --create api+✓ Created branch api from main and worktree @ <DEMO_DIR>/.demo-wt-core/w/acme.api+◎ Running post-start hooks: project:dev+[0m+$ wt list --full+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mmain…±[0m [1mRemote⇅[0m [1mCI[0m [1mCommit[0m [1mAge[0m+@ [2mapi[0m [2m_[22m [2m9b344c49[0m [2m1d[0m+^ main [2m^[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+2[0m [32m↑1[0m [32m+12[0m [31m-7[0m [2m0967fab5[0m [2m2h[0m++ [2mbilling[0m [2m_[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m+264[0m [31m-3[0m [32m⇡1[0m [2mf31634d7[0m [2m3d[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2mb10e3edd[0m [2m5d[0m++[2m○[22m [2mShowing 6 worktrees, 3 with changes, 2 ahead, 2 columns hidden[0m+[0m+$ wt remove+◎ Running pre-remove project:cleanup:+ flyctl scale count 0+Scaling app to 0 machines+◎ Removing api worktree & branch in background (same commit as main, _)+○ Switched to worktree for main @ <DEMO_DIR>/.demo-wt-core/w/acme+[0m[0mdiff --git a/docs/demos/snapshots/wt-list.snap b/docs/demos/snapshots/wt-list.snapnew file mode 100644index 000000000..e35834b30--- /dev/null+++ b/docs/demos/snapshots/wt-list.snap@@ -0,0 +1,32 @@+$ wt list+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add developm…[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+2[0m [32m↑1[0m [2m0967fab5[0m [2m2h[0m [2mfeat: add math ope…[0m++ [2mbilling[0m [2m_[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add developm…[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m⇡1[0m [2mf31634d7[0m [2m3d[0m [2mdocs: add FAQ sect…[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2mb10e3edd[0m [2m5d[0m [2mAdd project hooks[0m++[2m○[22m [2mShowing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden[0m+[0m+$ wt list --full+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mmain…±[0m [1mRemote⇅[0m [1mCI[0m [1mCommit[0m [1mAge[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+2[0m [32m↑1[0m [32m+12[0m [31m-7[0m [2m0967fab5[0m [2m2h[0m++ [2mbilling[0m [2m_[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m+264[0m [31m-3[0m [32m⇡1[0m [2mf31634d7[0m [2m3d[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2mb10e3edd[0m [2m5d[0m++[2m○[22m [2mShowing 5 worktrees, 3 with changes, 2 ahead, 2 columns hidden[0m+[0m+$ wt list --branches+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add dev…[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+2[0m [32m↑1[0m [2m0967fab5[0m [2m2h[0m [2mfeat: add mat…[0m++ [2mbilling[0m [2m_[22m[2m|[22m [2m|[0m [2m9b344c49[0m [2m1d[0m [2mdocs: add dev…[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m⇡1[0m [2mf31634d7[0m [2m3d[0m [2mdocs: add FAQ…[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2mb10e3edd[0m [2m5d[0m [2mAdd project h…[0m+ [2mdocs/readme[0m [2m/[22m[2m⊂[22m [2m[31m↓1[0m [2mb10e3edd[0m [2m5d[0m [2mAdd project h…[0m+ [2mspike/search[0m [2m/[22m[2m⊂[22m [2m[31m↓1[0m [2mb10e3edd[0m [2m5d[0m [2mAdd project h…[0m++[2m○[22m [2mShowing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 1 column hidden[0m+[0m[0mdiff --git a/docs/demos/snapshots/wt-merge.snap b/docs/demos/snapshots/wt-merge.snapnew file mode 100644index 000000000..9a075fb83--- /dev/null+++ b/docs/demos/snapshots/wt-merge.snap@@ -0,0 +1,37 @@+$ wt list+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9a898ce6[0m [2m1d[0m [2mdocs: add developme…[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+25[0m [32m↑1[0m [2me5bf91b7[0m [2m2h[0m [2mfeat: add math oper…[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m⇡1[0m [2m99a8f5d5[0m [2m3d[0m [2mdocs: add FAQ secti…[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2m77adea27[0m [2m5d[0m [2mAdd project hooks[0m++[2m○[22m [2mShowing 4 worktrees, 3 with changes, 2 ahead, 1 column hidden[0m+[0m+$ wt switch --create notes+✓ Created branch notes from main and worktree @ <DEMO_DIR>/.demo-wt-merge/w/acme.notes+[0m+$ wt merge+◎ Running pre-merge project:test:+ cargo nextest run+ Finished `test` profile [unoptimized + debuginfo] target(s) in 0.02s+ Starting 2 tests across 1 binary+ PASS [ 0.001s] acme::tests::test_add+ PASS [ 0.001s] acme::tests::test_add_zeros+------------+ Summary [ 0.002s] 2 tests run: 2 passed, 0 skipped+○ Already up to date with main (no new commits, no rebase needed)+◎ Removing notes worktree & branch in background (same commit as main, _)+○ Switched to worktree for main @ <DEMO_DIR>/.demo-wt-merge/w/acme+[0m+$ wt list --branches --full+ [1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mmain…±[0m [1mRemote⇅[0m [1mCI[0m [1mCommit[0m [1mAge[0m+@ main [2m^[22m[2m|[22m [2m|[0m [2m9a898ce6[0m [2m1d[0m++ hooks [36m+[39m[36m![39m [2m↑[22m [32m+25[0m [32m↑1[0m [32m+12[0m [31m-7[0m [2me5bf91b7[0m [2m2h[0m++ [2mnotes[0m [2m_[22m [2m9a898ce6[0m [2m1d[0m++ alpha [36m![39m[36m?[39m [2m↑[22m[2m⇡[22m [32m+105[0m [31m-14[0m [32m↑5[0m [32m+264[0m [31m-3[0m [32m⇡1[0m [2m99a8f5d5[0m [2m3d[0m++ beta [36m+[39m [2m↓[22m[2m|[22m [32m+2[0m [2m[31m↓1[0m [2m|[0m [2m77adea27[0m [2m5d[0m+ [2mdocs/readme[0m [2m/[22m[2m⊂[22m [2m[31m↓1[0m [2m77adea27[0m [2m5d[0m+ [2mspike/search[0m [2m/[22m[2m⊂[22m [2m[31m↓1[0m [2m77adea27[0m [2m5d[0m++[2m○[22m [2mShowing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 2 columns hidden[0m+[0m[0m