Playwright Terminal Testing¶

nspec uses Playwright MCP terminal tools to test the TUI. This is the primary way we verify TUI changes — unit tests check logic; Playwright checks what the user actually sees.

Setup¶

The terminal_* tools are provided by the jeremykuhnash/playwright-mcp fork, which extends the standard Playwright MCP server with terminal/TUI testing capabilities. The standard @playwright/mcp package provides browser automation only — it does not include terminal_* tools.

Clone and build the fork:

git clone https://github.com/jeremykuhnash/playwright-mcp.git
cd playwright-mcp
npm install

Then point your .mcp.json at the local build:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["/path/to/playwright-mcp/cli.js"]
    }
  }
}

Note

The fork's unified entry point (cli.js) provides both browser and terminal tools with no additional flags. Replace /path/to/playwright-mcp with your actual clone location.

Overview¶

The Playwright MCP server provides terminal_* tools that launch real terminal sessions, send keyboard input, capture screen output, and assert on content.

Tool Reference¶

Core Tools¶

Tool	Purpose
`terminal_spawn`	Launch a command in a real terminal session
`terminal_kill`	End session and clean up
`terminal_send_keys`	Keyboard input: `Enter`, `Escape`, `Tab`, `q`, `j`, `k`, `/`
`terminal_send_text`	Type literal text (search queries, spec IDs)
`terminal_snapshot`	Capture current screen as plain text
`terminal_assert`	Assert screen `contains` / `not_contains` / `matches`
`terminal_wait`	Wait for text/pattern to appear
`terminal_wait_idle`	Wait until output stops changing
`terminal_wait_prompt`	Wait for a shell prompt to appear
`terminal_resize`	Change terminal size for responsive testing

Multi-Pane & Window Management¶

Tool	Purpose
`terminal_split`	Split a session into multiple panes
`terminal_select_pane`	Switch focus to a specific pane
`terminal_send_to_pane`	Send input to a specific pane
`terminal_capture_pane`	Capture a specific pane's content
`terminal_list_panes`	List panes in a session
`terminal_new_window`	Create a new window in a session
`terminal_select_window`	Switch to a specific window
`terminal_list_windows`	List windows in a session

Session Management¶

Tool	Purpose
`terminal_list`	List active terminal sessions
`terminal_list_all`	List all sessions including detached
`terminal_attach`	Attach to an existing session
`terminal_detach`	Detach from a session (keep running)
`terminal_save`	Save session state

Recording & Baselines¶

Tool	Purpose
`terminal_record_start`	Start recording a session
`terminal_record_stop`	Stop recording
`terminal_record_save`	Save recording to a file
`terminal_dump`	Export terminal state as JSON baseline
`terminal_compare`	Diff current state against a saved baseline

Workflows¶

Verify a TUI Change¶

After editing any .tcss, widget, or screen code:

# 1. Launch the TUI
terminal_spawn command="nspec" args=["--tui"] cols=120 rows=35

# 2. Wait for it to load
terminal_wait pattern="nspec"

# 3. Capture the main screen
terminal_snapshot

# 4. Open a detail view
terminal_send_keys keys="Enter"
terminal_wait_idle
terminal_snapshot

# 5. Navigate between sections
terminal_send_keys keys="Tab"
terminal_wait_idle
terminal_snapshot

# 6. Clean up
terminal_send_keys keys="q"
terminal_kill

Verify a CLI Command¶

terminal_spawn command="nspec" args=["--validate"]
terminal_wait_idle
terminal_snapshot
terminal_assert contains="passed"
terminal_kill

Test Responsive Layout¶

terminal_spawn command="nspec" args=["--tui"] cols=80 rows=24
terminal_wait pattern="nspec"
terminal_snapshot           # Check narrow layout

terminal_resize cols=200 rows=50
terminal_wait_idle
terminal_snapshot           # Check wide layout
terminal_kill

Test Search¶

terminal_spawn command="nspec" args=["--tui"]
terminal_wait pattern="nspec"

# Open search
terminal_send_keys keys="/"
terminal_send_text text="MCP"
terminal_wait_idle
terminal_snapshot           # Filtered results visible?

# Navigate matches
terminal_send_keys keys="n"
terminal_snapshot

# Clear search
terminal_send_keys keys="Escape"
terminal_snapshot
terminal_kill

What to Verify¶

After changing...	Verify with...
`nspec.tcss`	Spawn TUI → snapshot main + detail screens
Widget rendering	Navigate to affected screen → snapshot
Section headers	Open detail → Tab through sections → snapshot each
Task tree	Open detail for spec with tasks → snapshot
Search	Type `/` → enter query → snapshot filtered results
Keybindings	Send key → snapshot → assert expected state
CLI output	Spawn CLI command → wait_idle → snapshot

Record a Session¶

Capture an interactive session for debugging or regression tracking:

terminal_spawn command="nspec" args=["--tui"] cols=120 rows=35
terminal_wait pattern="nspec"
terminal_record_start

# Perform actions...
terminal_send_keys keys="Enter"
terminal_wait_idle
terminal_send_keys keys="q"

terminal_record_stop
terminal_record_save path="work/recording-tui-navigation.json"
terminal_kill

Baselines¶

Save and compare terminal baselines using the work/ directory:

terminal_dump path="work/baseline-main-screen.json"
# ... make changes ...
terminal_compare expected_path="work/baseline-main-screen.json"