playwright-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright MCP Live Debugging

Playwright MCP 实时调试

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

通过浏览器自动化连接到运行中的VoiceTree Electron应用进行实时调试。

Quick Start (3 steps)

快速开始（3步）

1. Start Electron in debug mode

1. 启动Electron调试模式

bash

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.

bash

cd webapp && npm run electron:debug

此命令会启动Electron并在9222端口启用CDP，同时会在渲染器就绪后自动调用

prettySetupAppForElectronDebugging()

——加载

example_small

项目并生成3个调试终端。

由于这是一个长期运行的开发服务器，可搭配bash超时命令运行（例如30秒）。

2. Verify CDP is ready

2. 验证CDP已就绪

bash

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

Should return JSON with

"Browser": "Chrome/..."

bash

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

应返回包含

"Browser": "Chrome/..."

的JSON数据。

3. Go straight to inspecting — do NOT navigate

3. 直接开始检查——请勿导航

The app is already loaded with the project and debug terminals. Do not run

browser_navigate

page.goto()

— this would force-refresh and destroy the loaded state. Instead, jump directly to:

javascript

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

Use

browser_snapshot

browser_take_screenshot

for visual inspection.

应用已加载项目和调试终端。不要运行

browser_navigate

或

page.goto()

——这会强制刷新并破坏已加载的状态。请直接使用以下代码：

javascript

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

使用

browser_snapshot

或

browser_take_screenshot

进行可视化检查。

Opening a specific project (optional)

打开指定项目（可选）

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

javascript

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

如果需要加载特定项目而非测试示例：

javascript

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

工具	用途
`browser_snapshot`	获取当前页面的可访问性树
`browser_click`	通过引用点击元素
`browser_hover`	悬停在元素上
`browser_type`	在输入框中输入内容
`browser_evaluate`	在页面上下文运行JavaScript
`browser_tabs`	在标签页之间切换
`browser_wait_for`	等待文本/元素加载
`browser_take_screenshot`	捕获可视化截图

Accessing App APIs

访问应用API

The app exposes

window.electronAPI

with useful methods:

javascript

// 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

应用暴露了

window.electronAPI

接口，包含实用方法：

javascript

// 通过browser_evaluate调用
Object.keys(window.electronAPI.main)

// 核心方法:
window.electronAPI.main.prettySetupAppForElectronDebugging()  // 生成调试终端
window.electronAPI.main.initializeProject(path)  // 打开指定文件夹
window.electronAPI.main.getGraph()               // 获取图数据
window.electronAPI.main.getNode(id)              // 获取节点详情
window.electronAPI.main.loadSettings()           // 加载应用设置

Cytoscape Instance

Cytoscape实例

Access the graph directly via

window.cytoscapeInstance

javascript

// 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;

可通过

window.cytoscapeInstance

直接访问图实例：

javascript

// 获取图中所有节点
const cy = window.cytoscapeInstance;
cy.nodes().map(n => ({ id: n.id(), isContext: n.data('isContextNode') }));

// 获取节点数量
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

browser_take_screenshot

for visual inspection.

electron:debug

会自动加载项目并生成调试终端。当CDP就绪时，应用已处于正确页面。请勿：

运行
```
browser_navigate
```
/
```
page.goto()
```
—— 这会强制刷新应用并丢失所有已加载状态
在浏览器中访问
```
/json
```
—— 会导致同样的问题

请直接使用

browser_evaluate

来检查页面状态（例如查询cytoscape节点、检查DOM元素）。使用

browser_snapshot

或

browser_take_screenshot

进行可视化检查。

CRITICAL: Be surgical when killing Electron processes

重要提示：精准终止Electron进程

VoiceTree itself runs as an Electron process. A blanket

pkill -f electron

kill -9

on all Electron PIDs will kill your own host app. To kill only the debug Electron:

bash

undefined

VoiceTree本身作为Electron进程运行。使用

pkill -f electron

或

kill -9

终止所有Electron进程会同时关闭你的宿主应用。仅终止调试用Electron的方法：

bash

undefined

Find ONLY the process listening on port 9222

仅查找监听9222端口的进程

lsof -i :9222 -sTCP:LISTEN

Then kill that specific PID

然后终止该特定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.

kill <pid>


切勿使用`pkill -f electron`，或在未添加`-sTCP:LISTEN`过滤器的情况下终止`lsof -i :9222`找到的Electron PID —— 已连接的客户端（包括你自己的应用）也会被列出。

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>`

问题	解决方案
连接被拒绝	确保使用 `npm run electron:debug` 启动Electron
首次连接超时	重试 —— 首次连接可能较慢
选中了错误的标签页	使用 `browser_tabs action=select index=1`
弹出原生对话框	使用JavaScript API替代 —— 原生对话框无法被自动化
旧的Electron进程仍在运行	执行 `lsof -i :9222 -sTCP:LISTEN` 后终止对应PID

Architecture

架构

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

Claude Code → @playwright/mcp --cdp-endpoint http://localhost:9222 → CDP → Electron 应用 → VoiceTree 网页应用

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)

CDP仅能访问渲染进程，无法访问Electron主进程
支持热重载 —— 代码变更后无需重启
原生文件对话框无法被自动化 —— 请使用
```
electronAPI.main.initializeProject()
```
替代
同一时间仅支持一个调试会话（端口9222为硬编码）