playwright-mcp

Playwright MCP 浏览器自动化

你精通使用 Playwright MCP 服务进行实时浏览器交互。本技能将教你通过直接控制浏览器来浏览页面、检查元素、填写表单和调试 Web UI。

重要：这些是直接工具调用

MCP 工具是直接工具调用，与 Read、Grep 或 Bash 完全一样。它们不是 CLI 命令。

正确——直接调用工具：

Tool: mcp__playwright__browser_navigate
Parameters: { "url": "http://localhost:3010" }

错误——不要通过 shell 调用：

Bash: claude mcp call playwright browser_navigate ...  # This does not work

所有 Playwright MCP 工具都使用 mcp__playwright__ 前缀。

重要：交互前务必先获取快照

browser_snapshot 会返回一个无障碍树，其中包含每个交互元素的 ref 值。点击、输入或悬停之前，必须先获取快照——所有交互工具都需要 ref 值。

重要：注意输出大小

工具	输出大小	说明
browser_snapshot	中到大	完整的无障碍树，大小随页面复杂度变化
browser_take_screenshot	大	Base64 图像，请谨慎使用
browser_console_messages	不定	在日志繁杂的应用中可能非常大
browser_network_requests	不定	在 API 密集型页面中可能非常大
browser_navigate	小	仅返回页面标题
browser_click	小	点击后返回快照
browser_type	小	输入后返回快照

了解页面结构时，优先使用 browser_snapshot，而非 browser_take_screenshot。截图仅用于视觉验证。

工作流 1：浏览与检查

**触发条件：**用户说“打开此页面”“页面上有什么？”“检查 UI”“检查布局”

步骤

1. 浏览到页面：

   browser_navigate({ url: "http://localhost:3010/home/team-slug/settings" })
   

2. 获取页面结构（交互前务必执行此步骤）：

   browser_snapshot → accessibility tree with ref values for all elements
   

3. **分析快照：**根据 ref 值识别交互元素（按钮、链接、输入框）。向用户报告页面结构。

决策：快照还是截图

需求	使用
了解页面结构、查找元素	browser_snapshot（结构化，包含 ref 值）
视觉外观、布局问题、CSS 问题	browser_take_screenshot（视觉图像）
同时了解结构和外观	先获取快照；如需视觉检查，再截图

工作流 2：表单交互

**触发条件：**用户说“填写表单”“提交登录”“在字段中输入”“选择一个选项”

步骤

1. 获取快照以查找表单字段：

   browser_snapshot → identify input refs and their labels
   

2. 填写字段（根据复杂度选择）：

   • 单个字段：browser_type({ ref: "input-ref", text: "value" })
   • 多个字段：browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] })
   • 下拉菜单：browser_select_option({ ref: "select-ref", values: ["option-value"] })

3. 提交表单：

   browser_click({ ref: "submit-button-ref" })
   

4. 验证结果：

   browser_snapshot → check for success message, error states, or navigation
   

常用模式

• 对于多字段表单，browser_fill_form 比多次调用 browser_type 更快
• 可以使用 browser_press_key({ key: "Enter" }) 代替点击提交按钮
• 提交后，如有需要可等待：调用 browser_wait_for({ text: "Success" })，然后获取快照

工作流 3：调试调查

**触发条件：**用户说“调试页面”“检查错误”“正在发生哪些 API 调用？”“为什么无法正常工作？”

步骤

1. 浏览到出现问题的页面：

   browser_navigate({ url: "..." })
   

2. 并行运行以下工具（它们彼此独立）：

   browser_console_messages → JavaScript errors, warnings, logs
   browser_network_requests → API calls, failed requests, status codes
   

3. 获取页面快照：

   browser_snapshot → current UI state, error messages, loading states
   

4. 进一步调查：

   browser_evaluate({ expression: "document.querySelectorAll('.error').length" }) → run custom JS
   

工作流 4：多步骤浏览

**触发条件：**用户说“走完这个流程”“测试注册流程”“逐步完成向导”

步骤

1. 浏览到起始页面：

   browser_navigate({ url: "..." })
   

2. 对于每个步骤：

   browser_snapshot → find the next action
   browser_click({ ref: "..." }) or browser_type({ ref: "...", text: "..." })
   browser_wait_for({ text: "expected content" }) → if page loads async
   

3. 如出现对话框，请进行处理：

   browser_handle_dialog({ accept: true }) → confirm/alert/prompt
   

4. 如有需要，请返回：

   browser_navigate_back
   

工具参考

导航

工具	用途	参数
browser_navigate	前往 URL	url（必填）
browser_navigate_back	返回上一页	无
browser_wait_for	等待文本或指定时长	text 或 timeout（毫秒）
browser_tabs	列出／切换标签页	无，或使用 index 切换

检查

工具	用途	参数
browser_snapshot	获取包含 refs 的无障碍树	无
browser_take_screenshot	获取屏幕截图	无
browser_console_messages	获取 JS 控制台输出	无
browser_network_requests	获取网络活动	无

交互

工具	用途	参数
browser_click	点击元素	ref（来自 snapshot）
browser_type	输入文本	ref、text
browser_fill_form	填写多个字段	fields 数组，元素为 { ref, value }
browser_select_option	选择下拉选项	ref、values 数组
browser_hover	悬停在元素上	ref
browser_drag	拖放	startRef、endRef
browser_press_key	键盘输入	key（例如 "Enter"、"Tab"）
browser_file_upload	上传文件	ref、paths 数组
browser_handle_dialog	确认／关闭对话框	accept 布尔值

高级功能

工具	用途	参数
browser_evaluate	运行 JavaScript	expression
browser_resize	调整视口大小	width、height
browser_close	关闭页面	无
browser_install	安装浏览器	无
browser_run_code	运行 Playwright 代码	code 字符串

故障排除

“No browser running”或连接错误

Playwright MCP 服务会管理自己的浏览器实例。如果工具调用失败：

1. 尝试运行 browser_install，确保浏览器二进制文件可用
2. 尝试使用 browser_navigate 前往一个简单的 URL，这可能会初始化浏览器

导航后找不到元素

包含异步内容的页面可能尚未完成渲染：

1. 在 snapshot 之前使用 browser_wait_for({ text: "expected content" })
2. 使用 browser_wait_for({ timeout: 2000 }) 按指定时长等待

代理或内部域名

MCP 浏览器无法访问需要网络隧道的代理或内部域名。本地 Supabase 请直接使用 http://127.0.0.1:54321。

Snapshot 返回的内容过大

复杂页面会生成很大的无障碍树。如果输出过大：

1. 导航到特定子页面，而不是整个应用
2. 使用 browser_evaluate 查询特定元素