browser-devtools-cli

浏览器 DevTools CLI

使用 Playwright 进行浏览器自动化、调试和测试的命令行界面。此 CLI 面向浏览器平台；如需调试 Node.js 后端，请使用 node-devtools-cli（参见 node-devtools-cli 技能）。

安装

npm install -g browser-devtools-mcp

快速入门

# Navigate to a URL
browser-devtools-cli navigation go-to --url "https://example.com"

# Take a screenshot
browser-devtools-cli content take-screenshot --name "homepage"

# Get page content as text
browser-devtools-cli content get-as-text

基于 ref 的工作流（推荐用于 AI Agent）：先调用 a11y take-aria-snapshot 获取 refs（e1、e2、……），然后在 interaction click --selector "e1" 中使用 refs，或使用 content take-screenshot --annotate 获取带编号的元素标签。

全局选项

选项	描述	默认值
--port <number>	守护进程服务端口	2020
--session-id <string>	用于持久化浏览器状态的会话 ID	自动
--json	以 JSON 格式输出结果（推荐用于 AI）	false
--quiet	禁止显示日志消息	false
--verbose	启用调试输出	false
--timeout <ms>	操作超时时间	30000
--headless	以无头模式运行浏览器	true
--no-headless	在可见窗口中运行浏览器	-
--persistent	保留 cookies/localStorage	false
--no-persistent	在会话结束时清除状态	-
--user-data-dir <path>	浏览器用户数据目录	OS 临时目录
--use-system-browser	使用系统 Chrome	false
--browser-path <path>	自定义浏览器路径	自动

AI Agent 推荐选项：

# JSON output for parsing, quiet mode for clean output, session for state persistence
browser-devtools-cli --json --quiet --session-id "my-session" <command>

工具域

CLI 提供按域组织的工具：

域	描述	参考
navigation	页面导航（跳转、后退、前进、重新加载）
content	内容提取（屏幕截图、PDF、HTML、文本）
interaction	用户交互（点击、填写、悬停、滚动）
a11y	无障碍快照（ARIA、AX 树）
o11y	可观测性（Web Vitals、控制台、HTTP、跟踪）
debug	非阻塞调试（跟踪点、日志点、异常）
stub	HTTP 模拟（拦截、模拟、清除）
sync	同步（等待网络空闲）
react	React DevTools 集成
figma	Figma 设计比较
execute	批量执行 JavaScript（运行 execute；VM 中有 page、callTool）

Execute 同时支持 CLI 和 MCP。可用它运行 JavaScript 并批量调用工具：CLI 使用 run execute --code "<js>"（可选 --timeout-ms）；MCP 工具 execute 使用相同参数。在 VM 中：page（仅限浏览器）— Playwright Page；可使用 await page.title()、await page.evaluate(...) 等。callTool(name, input, returnOutput?) — 调用任意工具；始终使用 await；name 使用下划线形式（例如 'navigation_go-to'）；input 是一个对象（键使用 camelCase）；returnOutput: true 会将结果添加到响应的 toolOutputs 中。完整绑定和参数请参见 execute 参考。

CLI 管理命令

守护进程管理

browser-devtools-cli daemon status      # Check daemon status
browser-devtools-cli daemon info        # Show daemon info (version, uptime, sessions)
browser-devtools-cli daemon start       # Start daemon
browser-devtools-cli daemon stop        # Stop daemon
browser-devtools-cli daemon restart     # Restart daemon

会话管理

browser-devtools-cli session list                  # List active sessions
browser-devtools-cli session info <session-id>     # Show session details
browser-devtools-cli session delete <session-id>   # Delete a session

工具发现

browser-devtools-cli tools list              # List all available tools
browser-devtools-cli tools search <query>    # Search tools by name or description
browser-devtools-cli tools info <tool-name>  # Show tool details and parameters

配置

browser-devtools-cli config    # Show current configuration

更新

browser-devtools-cli update --check   # Check for updates
browser-devtools-cli update           # Check and install updates

示例

基本导航和屏幕截图

# Navigate to URL
browser-devtools-cli navigation go-to --url "https://example.com"

# Take screenshot
browser-devtools-cli content take-screenshot --name "homepage"

# Get page text
browser-devtools-cli content get-as-text

表单自动化

# Use same session for state persistence
SESSION="--session-id login-test"

# Navigate to login page
browser-devtools-cli $SESSION navigation go-to --url "https://app.example.com/login"

# Fill form fields
browser-devtools-cli $SESSION interaction fill --selector "#email" --value "[email protected]"
browser-devtools-cli $SESSION interaction fill --selector "#password" --value "password123"

# Submit form
browser-devtools-cli $SESSION interaction click --selector "button[type=submit]"

# Wait for navigation
browser-devtools-cli $SESSION sync wait-for-network-idle

# Capture result
browser-devtools-cli $SESSION content take-screenshot --name "dashboard"

性能分析

# Navigate
browser-devtools-cli navigation go-to --url "https://example.com"

# Get Web Vitals metrics
browser-devtools-cli --json o11y get-web-vitals

# Check console for errors
browser-devtools-cli --json o11y get-console-messages --type warning

# Analyze HTTP requests
browser-devtools-cli --json o11y get-http-requests

无障碍审计

# Navigate
browser-devtools-cli navigation go-to --url "https://example.com"

# Get ARIA snapshot
browser-devtools-cli a11y take-aria-snapshot

# Get detailed AX tree
browser-devtools-cli --json a11y take-ax-tree-snapshot --roles button,link,textbox

批量执行（execute）

# Run JavaScript in session VM (page + callTool available)
browser-devtools-cli run execute --code "return await page.title();"

# Batch multiple tools in one call (fewer round-trips)
browser-devtools-cli run execute --code "await callTool('a11y_take-aria-snapshot', {}, true); await callTool('content_take-screenshot', {}, true);"

API 模拟

# Mock API response
browser-devtools-cli stub mock-http-response \
  --pattern "**/api/users" \
  --body '[{"id": 1, "name": "Test User"}]'

# Navigate and test
browser-devtools-cli navigation go-to --url "https://app.example.com"

# Clear mocks
browser-devtools-cli stub clear

非阻塞调试

SESSION="--session-id debug-session"

# Navigate to app
browser-devtools-cli $SESSION navigation go-to --url "http://localhost:3000"

# Set tracepoint on a function
browser-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "app.js" \
  --line-number 42

# Add watch expression
browser-devtools-cli $SESSION debug add-watch --expression "this"

# Enable exception catching
browser-devtools-cli $SESSION debug put-exceptionpoint --state uncaught

# Interact with app (triggers probes)
browser-devtools-cli $SESSION interaction click --selector "#submit-btn"

# Get captured snapshots
browser-devtools-cli $SESSION --json debug get-probe-snapshots
browser-devtools-cli $SESSION --json debug get-probe-snapshots --types tracepoint,exceptionpoint

用于 CI/CD 的 Shell 脚本

#!/bin/bash
set -e

CLI="browser-devtools-cli --json --quiet --session-id ci-test-$$"

# Navigate
$CLI navigation go-to --url "https://example.com"

# Wait for load
$CLI sync wait-for-network-idle

# Take screenshot
$CLI content take-screenshot --name "ci-test"

# Get Web Vitals
VITALS=$($CLI o11y get-web-vitals)
echo "Web Vitals: $VITALS"

# Check for console errors
ERRORS=$($CLI o11y get-console-messages --type error)
if [ "$ERRORS" != "[]" ]; then
  echo "Console errors found: $ERRORS"
  exit 1
fi

# Cleanup
$CLI session delete "ci-test-$$"

交互模式（面向人类用户）

手动探索时，可使用交互式 REPL 模式：

browser-devtools-cli interactive
browser-devtools-cli --no-headless interactive   # With visible browser

命令	描述
help	显示可用命令
exit、quit	退出交互模式
<domain> <tool>	执行工具

Shell 补全

# Bash
browser-devtools-cli completion bash
echo 'eval "$(browser-devtools-cli completion bash)"' >> ~/.bashrc

# Zsh
browser-devtools-cli completion zsh
echo 'eval "$(browser-devtools-cli completion zsh)"' >> ~/.zshrc