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 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
66d0412250
commit
062f51e85f
@ -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:**
|
||||
|
||||
139
development/tui-testing.md
Normal file
139
development/tui-testing.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user