tmux-ui-tripwire
Overview
Tripwire tests drive the real ainb TUI binary in a detached tmux session, send keystrokes, capture the pane, and assert on rendered output. They are the ONLY tests that catch user-visible regressions the unit tests miss (e.g. plugin pipeline broken but cargo test green).
When to use this skill
- Writing a new
tripwire_*.rs test
- An existing tripwire fails and the cause isn't obvious from
cargo test output
- Tightening a tripwire whose assertions look weak (substring-OR on chrome strings)
- Diagnosing why a plugin "spawns but doesn't render"
Quick start — minimal viable tripwire
// crates/ainb-core/tests/tripwire_<feature>.rs
use std::path::PathBuf;
use std::process::Command;
use std::time::{Duration, Instant};
// 1. Skip gracefully if env can't support the test.
fn tmux_available() -> bool { /* see references/helpers.md */ }
fn ainb_bin() -> PathBuf { PathBuf::from(env!("CARGO_BIN_EXE_ainb")) }
#[test]
fn feature_renders_after_pressing_x() {
if !tmux_available() { eprintln!("SKIP: tmux"); return; }
// 2. Isolated HOME — seed onboarding.toml to skip wizard.
let home = tempfile::tempdir().unwrap();
seed_isolated_home(home.path());
// 3. Launch ainb tui in detached tmux session.
let session = format!("tripwire-{}", std::process::id());
Command::new("tmux").args(["new-session","-d","-s",&session,"-x","180","-y","50"]).status().unwrap();
let cmd = format!("HOME={} AINB_DISABLE_PLUGINS=1 exec {} tui",
home.path().display(), ainb_bin().display());
Command::new("tmux").args(["send-keys","-t",&session,&cmd,"Enter"]).status().unwrap();
// 4. Wait for HomeScreen — poll, don't bare-sleep.
let pre = poll_capture(&session, Instant::now() + Duration::from_secs(45),
|c| c.contains("Stats") && c.contains("[i]")).expect("HomeScreen never rendered");
// 5. Pre-press negative assertion — confirm we're not already on target screen.
assert!(!pre.contains("Usage Analytics"));
// 6. Send key WITHOUT Enter (single-char nav).
Command::new("tmux").args(["send-keys","-t",&session,"x"]).status().unwrap();
// 7. Post-press: positive marker AND negative placeholder.
let post = poll_capture(&session, Instant::now() + Duration::from_secs(30),
|c| c.contains("Expected Chrome") && !c.contains("Loading placeholder"))
.unwrap_or_else(|| capture_pane(&session));
Command::new("tmux").args(["kill-session","-t",&session]).status().ok();
assert!(post.contains("Expected Chrome"), "feature chrome never rendered:\n{post}");
assert!(!post.contains("Loading placeholder"), "stuck on placeholder:\n{post}");
}
Full copy-paste helper functions in references/helpers.md.
Required pre-work
| Step |
Command |
Why |
| Stage plugins (if test exercises plugin path) |
just stage-plugins |
Plugins live at dist/plugins/<id>/<id> and are re-signed for macOS AMFI |
| Build ainb |
cargo build -p ainb |
Test resolves binary via env!("CARGO_BIN_EXE_ainb") |
Hard rules (violating these costs hours)
- NEVER
tmux kill-server, pkill tmux, killall tmux, or wildcard kill. Only tmux kill-session -t <exact-name>. Other agents/dev sessions live in tmux.
- NEVER assert with substring-OR on chrome strings (
"ainb", "session", "Container"). They appear in sidebar regardless of whether the feature under test rendered. The original 7f.3 passed for 4+ commits while burndown was broken. Always pair a POSITIVE marker with a NEGATIVE placeholder check.
- NEVER append
Enter to a single-character keystroke. tmux send-keys -t S "i" for nav keys. Enter as a SEPARATE arg is only for committing a shell command line.
- NEVER use bare
sleep before capture. TUI render rate is 4–30 Hz. Use poll_capture(deadline, predicate) with 500 ms internal sleep.
- NEVER grep
Cargo.toml for the version in a shell wrapper. Workspace crates have version.workspace = true literally — grepping returns that string, breaks the wizard-skip seed. Use env!("CARGO_PKG_VERSION") in Rust or read [workspace.package].version from the root Cargo.toml.
- ALWAYS pair forward + return navigation. When a tripwire asserts "press X → screen Y rendered", add a sibling test (or trailing assertion) that "press Esc → previous screen returned". Forward-only tests pass while return paths silently break — exactly how the Esc-from-burndown swallow shipped past 4 existing tripwires in PR #128. The
plugin/handle_key wire is a one-way notification: it cannot signal "ignored, fall through", so plugins can swallow keys with no visible failure unless you test the round-trip end-to-end. See tripwire_burndown_esc_returns_home.rs for the canonical return-path shape.
- TOGGLE / edge keys are send-ONCE-then-poll — never resend.
poll_capture_resending re-presses the key on every iteration, which is correct ONLY for idempotent screen/focus keys (m once the screen is open, g once the graph is focused — re-pressing is a no-op). A toggle (v view-cycle, h hop, ⏎ recentre, c community, Backspace exit) gets flipped back on the next 400 ms tick, so the predicate may capture the OFF state and the test never converges (or flakes ~50/50). For those, send_key(S, key) ONCE then poll_capture(deadline, predicate) with no resend. (Cost: a "v did not open the map" failure whose final capture showed the neighbourhood — the map had opened then toggled shut on the next resend.)
Two-tmux pattern — KEEP BOTH PATHS
Keep BOTH a plugin-path test AND a non-plugin-path test:
| Test |
Key |
Env |
Purpose |
tripwire_real_data_in_tui |
i |
normal (plugins active) |
Verifies plugin pipeline end-to-end |
tripwire_sessions_screen |
s |
AINB_DISABLE_PLUGINS=1 |
Verifies host's own code path isn't broken by plugin refactors |
A refactor that breaks one shouldn't silently pass the other. If you add a new screen test, also add a regression test for the opposite path.
Workflow when a tripwire fails
- Run with
--nocapture — cargo test -p ainb --test tripwire_X -- --nocapture to see SKIP messages and panic output.
- Read the captured pane in the panic message — it shows what the test actually saw. Often the cause is staring at you (wizard, loading state, wrong screen).
- Check the JSONL log —
~/.agents-in-a-box/logs/agents-in-a-box-*.jsonl. Key markers:
"registered plugin" × N — discovery worked
"eager spawn failed: Broken pipe" + "plugin exited / pipe closed" — likely macOS AMFI silent kill (see references/amfi.md)
"inbound request" / "host->plugin response" — wire dialog active
plugin = "<name>" entries — host.log() from plugins
- Standalone-probe the plugin if Bug-2-like symptoms:
./dist/plugins/<id>/<id> </dev/null; echo $?
Exit 137 in <1ms = AMFI kill. Fix: just stage-plugins (re-signs).
When to consult the references
| Question |
File |
What's the exact code for poll_capture, seed_isolated_home, etc.? |
references/helpers.md |
| Why does my plugin exit 137 with no stderr? |
references/amfi.md |
How do I seed synthetic Claude data for $N.NN assertions? |
references/seed-data.md |
| Full gotcha checklist (10 silent traps) |
references/gotchas.md |
| Existing tripwires to copy patterns from |
ls crates/ainb-core/tests/tripwire_*.rs — each test is self-documenting via its filename + comments |
Source files
crates/ainb-core/tests/tripwire_*.rs — every tripwire on disk; read them directly, no manifest to keep in sync
scripts/build-plugins.sh — just stage-plugins implementation (codesign re-sign on macOS)
crates/ainb-core/src/main.rs setup_logging() — default EnvFilter widened to include plugin crates
1---2name: tmux-ui-tripwire3description: Write or debug tmux-driven end-to-end TUI tests ("tripwires") for the ainb terminal app. Use when the user asks to "write a tmux test", "add a tripwire", "verify the TUI in tmux", "test feature X by pressing key Y", "validate plugin Z renders", or when editing any file under `crates/ainb-core/tests/tripwire_*.rs`. Codifies the silent traps we hit during Phase 7 plugin testing — macOS AMFI SIGKILL of staged binaries (exit 137, no stderr), first-run wizard intercepting keystrokes, EnvFilter crate-name drift hiding logs, and substring-OR assertions that pass while the feature is broken. Use proactively before writing any new `tripwire_*.rs` test, and reference whenever an existing tripwire fails for non-obvious reasons.4metadata:5 source: https://skillmd.com/skills/stevengonsalvez/tmux-ui-tripwire6---78# tmux-ui-tripwire910## Overview1112Tripwire tests drive the real `ainb` TUI binary in a detached `tmux` session, send keystrokes, capture the pane, and assert on rendered output. They are the ONLY tests that catch user-visible regressions the unit tests miss (e.g. plugin pipeline broken but `cargo test` green).1314## When to use this skill1516- Writing a new `tripwire_*.rs` test17- An existing tripwire fails and the cause isn't obvious from `cargo test` output18- Tightening a tripwire whose assertions look weak (substring-OR on chrome strings)19- Diagnosing why a plugin "spawns but doesn't render"2021## Quick start — minimal viable tripwire2223```rust24// crates/ainb-core/tests/tripwire_<feature>.rs25use std::path::PathBuf;26use std::process::Command;27use std::time::{Duration, Instant};2829// 1. Skip gracefully if env can't support the test.30fn tmux_available() -> bool { /* see references/helpers.md */ }31fn ainb_bin() -> PathBuf { PathBuf::from(env!("CARGO_BIN_EXE_ainb")) }3233#[test]34fn feature_renders_after_pressing_x() {35 if !tmux_available() { eprintln!("SKIP: tmux"); return; }36 // 2. Isolated HOME — seed onboarding.toml to skip wizard.37 let home = tempfile::tempdir().unwrap();38 seed_isolated_home(home.path());3940 // 3. Launch ainb tui in detached tmux session.41 let session = format!("tripwire-{}", std::process::id());42 Command::new("tmux").args(["new-session","-d","-s",&session,"-x","180","-y","50"]).status().unwrap();43 let cmd = format!("HOME={} AINB_DISABLE_PLUGINS=1 exec {} tui",44 home.path().display(), ainb_bin().display());45 Command::new("tmux").args(["send-keys","-t",&session,&cmd,"Enter"]).status().unwrap();4647 // 4. Wait for HomeScreen — poll, don't bare-sleep.48 let pre = poll_capture(&session, Instant::now() + Duration::from_secs(45),49 |c| c.contains("Stats") && c.contains("[i]")).expect("HomeScreen never rendered");5051 // 5. Pre-press negative assertion — confirm we're not already on target screen.52 assert!(!pre.contains("Usage Analytics"));5354 // 6. Send key WITHOUT Enter (single-char nav).55 Command::new("tmux").args(["send-keys","-t",&session,"x"]).status().unwrap();5657 // 7. Post-press: positive marker AND negative placeholder.58 let post = poll_capture(&session, Instant::now() + Duration::from_secs(30),59 |c| c.contains("Expected Chrome") && !c.contains("Loading placeholder"))60 .unwrap_or_else(|| capture_pane(&session));61 Command::new("tmux").args(["kill-session","-t",&session]).status().ok();6263 assert!(post.contains("Expected Chrome"), "feature chrome never rendered:\n{post}");64 assert!(!post.contains("Loading placeholder"), "stuck on placeholder:\n{post}");65}66```6768Full copy-paste helper functions in `references/helpers.md`.6970## Required pre-work7172| Step | Command | Why |73|---|---|---|74| Stage plugins (if test exercises plugin path) | `just stage-plugins` | Plugins live at `dist/plugins/<id>/<id>` and are re-signed for macOS AMFI |75| Build ainb | `cargo build -p ainb` | Test resolves binary via `env!("CARGO_BIN_EXE_ainb")` |7677## Hard rules (violating these costs hours)78791. **NEVER `tmux kill-server`, `pkill tmux`, `killall tmux`, or wildcard kill.** Only `tmux kill-session -t <exact-name>`. Other agents/dev sessions live in tmux.802. **NEVER assert with substring-OR on chrome strings** (`"ainb"`, `"session"`, `"Container"`). They appear in sidebar regardless of whether the feature under test rendered. The original 7f.3 passed for 4+ commits while burndown was broken. Always pair a POSITIVE marker with a NEGATIVE placeholder check.813. **NEVER append `Enter` to a single-character keystroke.** `tmux send-keys -t S "i"` for nav keys. `Enter` as a SEPARATE arg is only for committing a shell command line.824. **NEVER use bare `sleep` before capture.** TUI render rate is 4–30 Hz. Use `poll_capture(deadline, predicate)` with 500 ms internal sleep.835. **NEVER grep `Cargo.toml` for the version in a shell wrapper.** Workspace crates have `version.workspace = true` literally — grepping returns that string, breaks the wizard-skip seed. Use `env!("CARGO_PKG_VERSION")` in Rust or read `[workspace.package].version` from the root `Cargo.toml`.846. **ALWAYS pair forward + return navigation.** When a tripwire asserts "press X → screen Y rendered", add a sibling test (or trailing assertion) that "press Esc → previous screen returned". Forward-only tests pass while return paths silently break — exactly how the Esc-from-burndown swallow shipped past 4 existing tripwires in PR #128. The `plugin/handle_key` wire is a one-way notification: it cannot signal "ignored, fall through", so plugins can swallow keys with no visible failure unless you test the round-trip end-to-end. See `tripwire_burndown_esc_returns_home.rs` for the canonical return-path shape.857. **TOGGLE / edge keys are send-ONCE-then-poll — never resend.** `poll_capture_resending` re-presses the key on every iteration, which is correct ONLY for idempotent screen/focus keys (`m` once the screen is open, `g` once the graph is focused — re-pressing is a no-op). A **toggle** (`v` view-cycle, `h` hop, `⏎` recentre, `c` community, `Backspace` exit) gets flipped back on the next 400 ms tick, so the predicate may capture the OFF state and the test never converges (or flakes ~50/50). For those, `send_key(S, key)` ONCE then `poll_capture(deadline, predicate)` with no resend. (Cost: a "v did not open the map" failure whose final capture showed the neighbourhood — the map had opened then toggled shut on the next resend.)8687## Two-tmux pattern — KEEP BOTH PATHS8889Keep BOTH a plugin-path test AND a non-plugin-path test:9091| Test | Key | Env | Purpose |92|---|---|---|---|93| `tripwire_real_data_in_tui` | `i` | normal (plugins active) | Verifies plugin pipeline end-to-end |94| `tripwire_sessions_screen` | `s` | `AINB_DISABLE_PLUGINS=1` | Verifies host's own code path isn't broken by plugin refactors |9596A refactor that breaks one shouldn't silently pass the other. If you add a new screen test, also add a regression test for the opposite path.9798## Workflow when a tripwire fails991001. **Run with `--nocapture`** — `cargo test -p ainb --test tripwire_X -- --nocapture` to see SKIP messages and panic output.1012. **Read the captured pane in the panic message** — it shows what the test actually saw. Often the cause is staring at you (wizard, loading state, wrong screen).1023. **Check the JSONL log** — `~/.agents-in-a-box/logs/agents-in-a-box-*.jsonl`. Key markers:103 - `"registered plugin"` × N — discovery worked104 - `"eager spawn failed: Broken pipe"` + `"plugin exited / pipe closed"` — likely macOS AMFI silent kill (see `references/amfi.md`)105 - `"inbound request"` / `"host->plugin response"` — wire dialog active106 - `plugin = "<name>"` entries — `host.log()` from plugins1074. **Standalone-probe the plugin** if Bug-2-like symptoms:108 ```109 ./dist/plugins/<id>/<id> </dev/null; echo $?110 ```111 Exit 137 in <1ms = AMFI kill. Fix: `just stage-plugins` (re-signs).112113## When to consult the references114115| Question | File |116|---|---|117| What's the exact code for `poll_capture`, `seed_isolated_home`, etc.? | `references/helpers.md` |118| Why does my plugin exit 137 with no stderr? | `references/amfi.md` |119| How do I seed synthetic Claude data for `$N.NN` assertions? | `references/seed-data.md` |120| Full gotcha checklist (10 silent traps) | `references/gotchas.md` |121| Existing tripwires to copy patterns from | `ls crates/ainb-core/tests/tripwire_*.rs` — each test is self-documenting via its filename + comments |122123## Source files124125- `crates/ainb-core/tests/tripwire_*.rs` — every tripwire on disk; read them directly, no manifest to keep in sync126- `scripts/build-plugins.sh` — `just stage-plugins` implementation (codesign re-sign on macOS)127- `crates/ainb-core/src/main.rs` `setup_logging()` — default `EnvFilter` widened to include plugin crates