tmux CLI Testing

Test CLI applications by running them in tmux sessions, waiting for conditions, sending input, and asserting on output. Never sleep - always wait on a condition.

Helpers

Source the helper script for all primitives:

bash

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh

Quick Reference

Function	Purpose
`tmux_start <session> <cmd>`	Launch command in detached tmux session
`tmux_kill <session>`	Kill session
`tmux_is_alive <session>`	Check if session is running
`tmux_capture <session>`	Get pane text
`tmux_capture_ansi <session>`	Get pane text with ANSI codes
`tmux_wait_for <session> <text> [timeout]`	Poll until text appears
`tmux_wait_for_regex <session> <pattern> [timeout]`	Poll until regex matches
`tmux_wait_gone <session> <text> [timeout]`	Poll until text disappears
`tmux_wait_exit <session> [timeout]`	Poll until process exits
`tmux_send <session> <keys...>`	Send keys (tmux key names)
`tmux_type <session> <text>`	Type literal text
`tmux_assert_contains <session> <text> [label]`	Assert text present
`tmux_assert_not_contains <session> <text> [label]`	Assert text absent
`tmux_assert_matches <session> <pattern> [label]`	Assert regex matches
`tmux_send_and_wait <session> <keys> <text> [timeout]`	Send then wait
`tmux_test <session> <cmd> <ready_text> <fn>`	Full lifecycle test

Configuration

Override defaults before calling functions:

bash

TMUX_TEST_POLL_INTERVAL=0.3  # seconds between polls
TMUX_TEST_TIMEOUT=30         # max wait seconds
TMUX_TEST_WIDTH=120          # terminal columns
TMUX_TEST_HEIGHT=30          # terminal rows

Workflow

Every test follows this pattern:

1. Start session with command
2. Wait for ready signal (text appearing)
3. Interact (send keys, wait for responses)
4. Assert on captured output
5. Kill session

Minimal Example

bash

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh

tmux_start "test-help" "./crates/target/debug/gpu --help"
tmux_wait_for "test-help" "Usage:" 10
tmux_assert_contains "test-help" "run"
tmux_assert_contains "test-help" "dashboard"
tmux_kill "test-help"

Using tmux_test for Lifecycle

bash

test_help_page() {
    local s="$1"
    tmux_assert_contains "$s" "run" "help shows run command"
    tmux_assert_contains "$s" "dashboard" "help shows dashboard command"
    tmux_assert_not_contains "$s" "ERROR" "no errors in help"
}

tmux_test "help-test" "./crates/target/debug/gpu --help" "Usage:" test_help_page

GPU CLI Patterns

Testing the Dashboard (TUI)

bash

source .claude/skills/tmux-cli-test/scripts/tmux_helpers.sh
TMUX_TEST_WIDTH=140
TMUX_TEST_HEIGHT=35

GPU_BIN="./crates/target/debug/gpu"

tmux_start "dash" "$GPU_BIN dashboard"
tmux_wait_for "dash" "Pods" 15

# Verify panels rendered
tmux_assert_contains "dash" "Pods" "pods panel visible"
tmux_assert_contains "dash" "Jobs" "jobs panel visible"

# Navigate with keys
tmux_send "dash" j
tmux_send "dash" j
tmux_wait_for "dash" "▶" 5  # selection cursor

# Switch panel
tmux_send "dash" Tab
tmux_wait_for_regex "dash" "Jobs.*selected" 5

# Open help overlay
tmux_send "dash" '?'
tmux_wait_for "dash" "Help" 5
tmux_assert_contains "dash" "Keybindings" "help shows keybindings"

# Close help
tmux_send "dash" Escape
tmux_wait_gone "dash" "Keybindings" 5

# Quit
tmux_send "dash" q
tmux_wait_exit "dash" 5

Testing Interactive Prompts

bash

tmux_start "init" "$GPU_BIN init"
tmux_wait_for "init" "project" 10

# Type project name
tmux_type "init" "my-test-project"
tmux_send "init" Enter

# Wait for next prompt
tmux_wait_for "init" "GPU" 10

# Select GPU with arrow keys
tmux_send "init" j j Enter
tmux_wait_for "init" "provider" 10

tmux_kill "init"

Testing Command Output

bash

tmux_start "status" "$GPU_BIN status"
tmux_wait_for_regex "status" "(No active|Pod)" 10

FRAME=$(tmux_capture "status")
if echo "$FRAME" | grep -q "No active"; then
    echo "No pods running - expected for cold test"
elif echo "$FRAME" | grep -q "Pod"; then
    tmux_assert_matches "status" "Pod.*READY\|ACTIVE" "pod in valid state"
fi

tmux_wait_exit "status" 15

Testing Error Handling

bash

tmux_start "bad-cmd" "$GPU_BIN run --nonexistent-flag"
tmux_wait_for_regex "bad-cmd" "error|Error|unknown" 10
tmux_assert_not_contains "bad-cmd" "panic" "no panics on bad input"
tmux_wait_exit "bad-cmd" 5

Testing Long-Running Commands with Ctrl-C

bash

tmux_start "run-job" "$GPU_BIN run python -c 'import time; time.sleep(3600)'"
tmux_wait_for "run-job" "Running" 30

# Interrupt
tmux_send "run-job" C-c
tmux_wait_for_regex "run-job" "cancel|interrupt|stopped" 10
tmux_wait_exit "run-job" 10

Docker Containers

For testing CLI apps running inside Docker containers (e.g., FTR testing), source the Docker helpers:

bash

source .claude/skills/tmux-cli-test/scripts/tmux_docker_helpers.sh
TMUX_DOCKER_CONTAINER="gpu-ftr-alex-chen-001"
# TMUX_DOCKER_SESSION="test"  # default, override if needed

Set

TMUX_DOCKER_CONTAINER

once, then all

docker_tmux_*

calls route through

docker exec

to that container. Same API as the local helpers but without session/container args:

Function	Purpose
`docker_tmux_send <keys...>`	Send tmux keys
`docker_tmux_type <text>`	Type literal text
`docker_tmux_capture`	Get pane text
`docker_tmux_capture_ansi`	Get pane text with ANSI codes
`docker_tmux_wait_for <text> [timeout]`	Poll until text appears
`docker_tmux_wait_regex <pattern> [timeout]`	Poll until regex matches
`docker_tmux_wait_gone <text> [timeout]`	Poll until text disappears
`docker_tmux_assert_contains <text> [label]`	Assert text present
`docker_tmux_assert_not_contains <text> [label]`	Assert text absent
`docker_tmux_assert_matches <pattern> [label]`	Assert regex matches
`docker_tmux_send_and_wait <keys> <text> [timeout]`	Send then wait

Docker Example

bash

source .claude/skills/tmux-cli-test/scripts/tmux_docker_helpers.sh
TMUX_DOCKER_CONTAINER="gpu-ftr-alex-chen-001"

docker_tmux_send "gpu dashboard" Enter
docker_tmux_wait_for "Pods" 15
docker_tmux_capture
docker_tmux_send j
docker_tmux_send "?"
docker_tmux_wait_for "Help" 5
docker_tmux_assert_contains "Keybindings" "help shows keybindings"
docker_tmux_send Escape
docker_tmux_wait_gone "Help" 5
docker_tmux_send q

Writing Tests Inline

When no helper script is needed (quick one-off checks), use tmux commands directly:

bash

# Start
tmux new-session -d -s test -x 120 -y 30 "./crates/target/debug/gpu dashboard"

# Poll for ready (inline wait loop)
for i in $(seq 1 100); do
    tmux capture-pane -t test -p | grep -q "Pods" && break
    sleep 0.3
done

# Assert
FRAME=$(tmux capture-pane -t test -p)
echo "$FRAME" | grep -q "Pods" && echo "PASS" || echo "FAIL"

# Cleanup
tmux send-keys -t test q
tmux kill-session -t test 2>/dev/null

Anti-Patterns

Bad	Good	Why
`sleep 3`	`tmux_wait_for s "Ready"`	Sleeps are flaky and slow
`sleep 5 && tmux capture-pane`	`tmux_wait_for s "expected" && tmux_capture s`	Condition, not duration
Hardcoded binary path	`GPU_BIN=./crates/target/debug/gpu`	Easy to switch debug/release
No cleanup on failure	`tmux_test` or explicit `tmux_kill`	Leftover sessions break next run
`grep -q` without timeout loop	`tmux_wait_for`	Text may not be rendered yet
Checking `.len()` of TUI text	Check display content only	Unicode width != byte length

Debugging Failed Tests

When a test fails, capture the frame for diagnosis:

bash

# Capture what's actually on screen
tmux_capture "session-name"

# Save to file for comparison
tmux_capture_to_file "session-name" "/tmp/failed-frame.txt"

# Capture with colors to verify styling
tmux_capture_ansi "session-name"

Session Naming Convention

Use descriptive, prefixed session names to avoid collisions:

gpu-test-dashboard
gpu-test-init
gpu-test-run-basic
gpu-test-status
gpu-test-error-handling

tmux-cli-test

NPX Install

Tags

SKILL.md Content

tmux CLI Testing

Helpers

Quick Reference

Configuration

Workflow

Minimal Example

Using tmux_test for Lifecycle

GPU CLI Patterns

Testing the Dashboard (TUI)

Testing Interactive Prompts

Testing Command Output

Testing Error Handling

Testing Long-Running Commands with Ctrl-C

Docker Containers

Docker Example

Writing Tests Inline

Anti-Patterns

Debugging Failed Tests

Session Naming Convention