/playwright-debug

name: playwright-debug
description: This skill should be used when the user asks to "debug the electron app", "connect playwright to VoiceTree", "take screenshots of the running app", "interact with the live UI", "inspect the running application", or "test UI elements live". Provides step-by-step instructions for connecting Playwright MCP to a running Electron app for live debugging and automation.

Playwright MCP Live Debugging

Connect to a running VoiceTree Electron app for live debugging via browser automation.

Quick Start (3 steps)

1. Start Electron in debug mode

cd webapp && npm run electron:debug

This starts Electron with CDP enabled on port 9222 **and** automatically calls `prettySetupAppForElectronDebugging()` once the renderer is ready — loading the `example_small` project and spawning 3 debug terminals.

> Run with a bash timeout (e.g. 30s) since this is a long-running dev server.

2. Verify CDP is ready

curl -s http://localhost:9222/json/version

Should return JSON with `"Browser": "Chrome/..."`.

3. Go straight to inspecting — do NOT navigate

The app is already loaded with the project and debug terminals. **Do not** run `browser_navigate` or `page.goto()` — this would force-refresh and destroy the loaded state. Instead, jump directly to:

// browser_evaluate — check cytoscape nodes
const cy = window.cytoscapeInstance;
JSON.stringify({ nodeCount: cy.nodes().length, edgeCount: cy.edges().length });

Use `browser_snapshot` or `browser_take_screenshot` for visual inspection.

Opening a specific project (optional)

If you need a specific project instead of the test fixture:

await window.electronAPI.main.initializeProject('/path/to/folder');

Available Tools

| Tool | Purpose | |------|---------| | `browser_snapshot` | Get accessibility tree of current page | | `browser_click` | Click elements by ref | | `browser_hover` | Hover over elements | | `browser_type` | Type into inputs | | `browser_evaluate` | Run JavaScript in page context | | `browser_tabs` | Switch between tabs | | `browser_wait_for` | Wait for text/elements | | `browser_take_screenshot` | Capture visual screenshot |

Accessing App APIs

The app exposes `window.electronAPI` with useful methods:

// Via browser_evaluate
Object.keys(window.electronAPI.main)

// Key methods:
window.electronAPI.main.prettySetupAppForElectronDebugging()  // Spawn debug terminals
window.electronAPI.main.initializeProject(path)  // Open a folder
window.electronAPI.main.getGraph()               // Get graph data
window.electronAPI.main.getNode(id)              // Get node details
window.electronAPI.main.loadSettings()           // App settings

Cytoscape Instance

Access the graph directly via `window.cytoscapeInstance`:

// Get all nodes in the graph
const cy = window.cytoscapeInstance;
cy.nodes().map(n => ({ id: n.id(), isContext: n.data('isContextNode') }));

// Get node count
cy.nodes().length;

CRITICAL: Do NOT navigate or refresh the app

`electron:debug` automatically loads the project and spawns debug terminals. The app is **already at the right page** when CDP is ready. Do NOT:

• Run `browser_navigate` / `page.goto()` — this will force-refresh the app and lose all loaded state
• Hit `/json` in the browser — same problem

Instead, **go straight to `browser_evaluate`** to inspect the page state (e.g. query cytoscape nodes, check DOM elements). Use `browser_snapshot` or `browser_take_screenshot` for visual inspection.

CRITICAL: Be surgical when killing Electron processes

VoiceTree itself runs as an Electron process. A blanket `pkill -f electron` or `kill -9` on all Electron PIDs **will kill your own host app**. To kill only the debug Electron:

# Find ONLY the process listening on port 9222
lsof -i :9222 -sTCP:LISTEN
# Then kill that specific PID
kill <pid>

Never use `pkill -f electron` or kill Electron PIDs found via `lsof -i :9222` without the `-sTCP:LISTEN` filter — connected clients (including your own app) also show up.

Troubleshooting

| Issue | Solution | |-------|----------| | Connection refused | Ensure Electron started with `npm run electron:debug` | | Timeout on first connect | Retry - first connection can be slow | | Wrong tab selected | `browser_tabs action=select index=1` | | Native dialog opened | Use JavaScript APIs instead - native dialogs can't be automated | | Old Electron still running | `lsof -i :9222 -sTCP:LISTEN` then `kill <that-pid>` |

Architecture

Claude Code → @playwright/mcp --cdp-endpoint http://localhost:9222 → CDP → Electron App → VoiceTree Webapp

Notes

• CDP only accesses renderer process, not Electron main process
• Hot reload works - no restart needed on code changes
• Native file dialogs cannot be automated - use `electronAPI.main.initializeProject()` instead
• Only one debug session at a time (port 9222 hardcoded)