Skip to content

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.md
index 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/build
index 8e88cd446..9fbc7e26c 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -43,6 +43,7 @@ from shared import ( # noqa: E402
SIZE_DOCS,
SIZE_SOCIAL,
record_text,
+ record_snapshot,
build_tape_replacements,
ensure_vhs_binary,
)
@@ -50,6 +51,10 @@ from shared import ( # noqa: E402
REPO_ROOT = SCRIPT_DIR.parent.parent
OUT_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_name
for tape_file, output_name, setup_func in demos
}
diff --git a/docs/demos/shared/__init__.py b/docs/demos/shared/__init__.py
index a4e1c3937..dde40339b 100644
--- a/docs/demos/shared/__init__.py
+++ b/docs/demos/shared/__init__.py
@@ -27,6 +27,9 @@ from .lib import (
# Text output recording
record_text,
build_tape_replacements,
+ # Snapshot recording
+ extract_commands_from_tape,
+ record_snapshot,
# External dependencies
ensure_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.py
index 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")
+
+
@dataclass
class DemoSize:
"""Canvas and font size for demo recording."""
diff --git a/docs/demos/snapshots/wt-commit.snap b/docs/demos/snapshots/wt-commit.snap
new file mode 100644
index 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
+
+$ 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
+
+$ 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.
+
diff --git a/docs/demos/snapshots/wt-core.snap b/docs/demos/snapshots/wt-core.snap
new file mode 100644
index 000000000..bf5006924
--- /dev/null
+++ b/docs/demos/snapshots/wt-core.snap
@@ -0,0 +1,35 @@
+$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ main ^| | 9b344c49 1d docs: add developm…
++ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add math ope…
++ billing _| | 9b344c49 1d docs: add developm…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ sect…
++ beta + ↓| +2 ↓1 | b10e3edd 5d Add project hooks
+
+○ Showing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden
+
+$ wt switch alpha
+○ Switched to worktree for alpha @ <DEMO_DIR>/.demo-wt-core/w/acme.alpha
+
+$ 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
+
+$ wt list --full
+ Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
+@ api _ 9b344c49 1d
+^ main ^| | 9b344c49 1d
++ hooks +! ↑ +2 ↑1 +12 -7 0967fab5 2h
++ billing _| | 9b344c49 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 f31634d7 3d
++ beta + ↓| +2 ↓1 | b10e3edd 5d
+
+○ Showing 6 worktrees, 3 with changes, 2 ahead, 2 columns hidden
+
+$ 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
+
diff --git a/docs/demos/snapshots/wt-list.snap b/docs/demos/snapshots/wt-list.snap
new file mode 100644
index 000000000..e35834b30
--- /dev/null
+++ b/docs/demos/snapshots/wt-list.snap
@@ -0,0 +1,32 @@
+$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ main ^| | 9b344c49 1d docs: add developm…
++ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add math ope…
++ billing _| | 9b344c49 1d docs: add developm…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ sect…
++ beta + ↓| +2 ↓1 | b10e3edd 5d Add project hooks
+
+○ Showing 5 worktrees, 3 with changes, 2 ahead, 1 column hidden
+
+$ wt list --full
+ Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
+@ main ^| | 9b344c49 1d
++ hooks +! ↑ +2 ↑1 +12 -7 0967fab5 2h
++ billing _| | 9b344c49 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 f31634d7 3d
++ beta + ↓| +2 ↓1 | b10e3edd 5d
+
+○ Showing 5 worktrees, 3 with changes, 2 ahead, 2 columns hidden
+
+$ wt list --branches
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ main ^| | 9b344c49 1d docs: add dev…
++ hooks +! ↑ +2 ↑1 0967fab5 2h feat: add mat…
++ billing _| | 9b344c49 1d docs: add dev…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 f31634d7 3d docs: add FAQ…
++ beta + ↓| +2 ↓1 | b10e3edd 5d Add project h…
+ docs/readme /⊂ ↓1 b10e3edd 5d Add project h…
+ spike/search /⊂ ↓1 b10e3edd 5d Add project h…
+
+○ Showing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 1 column hidden
+
diff --git a/docs/demos/snapshots/wt-merge.snap b/docs/demos/snapshots/wt-merge.snap
new file mode 100644
index 000000000..9a075fb83
--- /dev/null
+++ b/docs/demos/snapshots/wt-merge.snap
@@ -0,0 +1,37 @@
+$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ main ^| | 9a898ce6 1d docs: add developme…
++ hooks +! ↑ +25 ↑1 e5bf91b7 2h feat: add math oper…
++ alpha !? ↑⇡ +105 -14 ↑5 ⇡1 99a8f5d5 3d docs: add FAQ secti…
++ beta + ↓| +2 ↓1 | 77adea27 5d Add project hooks
+
+○ Showing 4 worktrees, 3 with changes, 2 ahead, 1 column hidden
+
+$ wt switch --create notes
+✓ Created branch notes from main and worktree @ <DEMO_DIR>/.demo-wt-merge/w/acme.notes
+
+$ 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
+
+$ wt list --branches --full
+ Branch Status HEAD± main↕ main…± Remote⇅ CI Commit Age
+@ main ^| | 9a898ce6 1d
++ hooks +! ↑ +25 ↑1 +12 -7 e5bf91b7 2h
++ notes _ 9a898ce6 1d
++ alpha !? ↑⇡ +105 -14 ↑5 +264 -3 ⇡1 99a8f5d5 3d
++ beta + ↓| +2 ↓1 | 77adea27 5d
+ docs/readme /⊂ ↓1 77adea27 5d
+ spike/search /⊂ ↓1 77adea27 5d
+
+○ Showing 5 worktrees, 2 remote branches, 3 with changes, 2 ahead, 2 columns hidden
+