From 062f51e85ffaf0705dec3bbbc22a6ecc6b1e566e Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Sun, 1 Mar 2026 20:13:37 -0600 Subject: [PATCH] docs: add tui-testing context and fix MCP config location Add mcp-tui-driver documentation with tool reference, workflow guide, and correct MCP config location (~/.claude.json, not ~/.claude/.mcp.json). Add context loading keyword entry for TUI testing topics. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 + development/tui-testing.md | 139 +++++++++++++++++++++++++++++++++++++ 2 files changed, 140 insertions(+) create mode 100644 development/tui-testing.md diff --git a/CLAUDE.md b/CLAUDE.md index b5c4fb9..d6c6ed6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,6 +29,7 @@ When a topic comes up, load `{tech}/CONTEXT.md` + `{tech}/troubleshooting.md`. F | database, postgres, redis, sql | `databases/` | | backup, restic, snapshot, restore, retention | `backups/` | | workstation, dotfiles, symlink, fish, starship, mangohud, zed, fish config, fish alias, tmux, tmux alias | `workstation/` | +| tui testing, mcp-tui-driver, tui automation, terminal ui test | `development/tui-testing.md` | | scheduled task, claude-scheduled, headless claude, timer, cowork | `~/.claude/skills/create-scheduled-task/SKILL.md` | **Special loads:** diff --git a/development/tui-testing.md b/development/tui-testing.md new file mode 100644 index 0000000..6f55e88 --- /dev/null +++ b/development/tui-testing.md @@ -0,0 +1,139 @@ +# TUI Testing with mcp-tui-driver + +## Overview +[mcp-tui-driver](https://github.com/michaellee8/mcp-tui-driver) is an MCP server that provides Playwright-like automation for TUI applications. It enables Claude Code to launch, view, interact with, and test terminal UI apps through structured MCP tools. + +## Installation +```bash +cargo install --git https://github.com/michaellee8/mcp-tui-driver +``` +Binary installs to: `~/.cargo/bin/mcp-tui-driver` + +### MCP Config +Configured globally in `~/.claude.json` under the top-level `mcpServers` key: +```json +"tui-driver": { + "command": "/home/cal/.cargo/bin/mcp-tui-driver", + "args": [] +} +``` +> **Note:** `~/.claude/.mcp.json` is NOT read by Claude Code. Global MCP servers go in `~/.claude.json`. + +### Updating +```bash +cargo install --git https://github.com/michaellee8/mcp-tui-driver --force +``` + +## Tool Reference (23 tools) + +### Session Management +| Tool | Description | +|------|-------------| +| `tui_launch` | Start a new TUI app session (command, args, cols, rows) | +| `tui_close` | Terminate a session and its process | +| `tui_list_sessions` | List all active sessions | +| `tui_get_session` | Get session details and status | +| `tui_resize` | Change terminal dimensions | + +### Viewing +| Tool | Description | +|------|-------------| +| `tui_text` | Get plain text from the terminal screen | +| `tui_snapshot` | Accessibility-style snapshot with element references (like Playwright locators) | +| `tui_screenshot` | Capture terminal as PNG image | + +### Keyboard Input +| Tool | Description | +|------|-------------| +| `tui_press_key` | Press a single key or key combo (e.g., `Ctrl+c`, `Enter`) | +| `tui_press_keys` | Press multiple keys sequentially | +| `tui_send_text` | Send raw text string to the terminal | + +### Mouse Input +| Tool | Description | +|------|-------------| +| `tui_click` | Click a snapshot element by reference | +| `tui_click_at` | Click at specific terminal coordinates (row, col) | +| `tui_double_click` | Double-click an element | +| `tui_right_click` | Right-click an element | + +### Waiting +| Tool | Description | +|------|-------------| +| `tui_wait_for_text` | Block until specific text appears on screen | +| `tui_wait_for_idle` | Block until screen stops changing | + +### Scripting +| Tool | Description | +|------|-------------| +| `tui_get_code_interface` | Get TypeScript API definitions for scripting | +| `tui_run_code` | Execute JavaScript automation scripts | + +### Debug +| Tool | Description | +|------|-------------| +| `tui_get_input` | Get raw input buffer with escape sequences | +| `tui_get_output` | Get raw PTY output | +| `tui_get_scrollback` | Get lines scrolled off-screen | +| `tui_send_signal` | Send signals (SIGINT, SIGTERM, etc.) | + +## Typical Testing Workflow + +1. **Launch** the TUI app under test: + ``` + tui_launch → command: "python", args: ["-m", "myapp"], cols: 120, rows: 40 + ``` + +2. **Wait** for it to render: + ``` + tui_wait_for_text → text: "Welcome" or tui_wait_for_idle + ``` + +3. **Inspect** the screen: + ``` + tui_snapshot → returns accessibility tree with element refs + tui_screenshot → returns PNG for visual verification + ``` + +4. **Interact** with the app: + ``` + tui_press_key → key: "Tab" (navigate) + tui_send_text → text: "search query" (type into fields) + tui_press_key → key: "Enter" (confirm) + tui_click → ref: "button-submit" (click element from snapshot) + ``` + +5. **Assert** expected state: + ``` + tui_text → verify expected text content + tui_snapshot → verify element structure + ``` + +6. **Cleanup**: + ``` + tui_close → terminate the session + ``` + +## Key Concepts + +### Accessibility Snapshots +`tui_snapshot` returns a structured view of the terminal with labeled element references. These refs can be used with `tui_click`, `tui_double_click`, and `tui_right_click` — similar to Playwright's `getByRole()` locators but for terminal elements. + +### Multi-Session Support +Multiple TUI sessions can run concurrently. Each `tui_launch` returns a session ID used by all other tools. This enables: +- Testing multiple instances side by side +- Launching a helper process alongside the app under test +- Comparing output between different configurations + +### Asciicast Recording +Sessions record output in asciicast v3 format (.cast files) compatible with `asciinema play`. Useful for reviewing test sessions after the fact. + +### JavaScript Scripting +For complex automation sequences, `tui_run_code` accepts JavaScript with access to the full TUI automation API. Use `tui_get_code_interface` to get the TypeScript definitions. + +## Alternatives Considered +- **mcpterm** (https://github.com/dwrtz/mcpterm): Go-based PoC with only 2 tools (`run`, `runScreen`). Single session, no mouse support, no screenshots, no accessibility snapshots. Too minimal for systematic TUI testing. + +## Dependencies +- Rust toolchain (cargo) +- Uses: wezterm-term, portable-pty, boa_engine (JS), rmcp, image