062f51e85f
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>
140 lines
4.8 KiB
Markdown
140 lines
4.8 KiB
Markdown
# 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
|