Agent Skills: tmux-ui-tripwire

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)

1. 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.
2. 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.
3. 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.
4. NEVER use bare sleep before capture. TUI render rate is 4–30 Hz. Use poll_capture(deadline, predicate) with 500 ms internal sleep.
5. 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.
6. 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.
7. 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

1. Run with --nocapture — cargo test -p ainb --test tripwire_X -- --nocapture to see SKIP messages and panic output.
2. 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).
3. 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
4. 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