playwright-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright MCP Browser Automation

Playwright MCP 浏览器自动化

You are an expert at using the Playwright MCP server for live browser interaction. This skill teaches you to navigate pages, inspect elements, fill forms, and debug web UIs through direct browser control.

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

Critical: These Are Direct Tool Calls

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

MCP tools are direct tool calls — exactly like

Read

Grep

, or

Bash

. They are NOT CLI commands.

CORRECT — call the tool directly:

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

WRONG — do NOT shell out:

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

All Playwright MCP tools use the

mcp__playwright__

prefix.

MCP工具是直接工具调用——和

Read

、

Grep

或者

Bash

完全一样，它们不是CLI命令。

正确用法——直接调用工具：

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

错误用法——不要通过Shell调用：

Bash: claude mcp call playwright browser_navigate ...  # 这种方式无效

所有Playwright MCP工具都使用

mcp__playwright__

前缀。

Critical: Always Snapshot Before Interacting

重要提示：交互前务必生成快照

browser_snapshot

returns an accessibility tree with

ref

values for every interactive element. You must snapshot before clicking, typing, or hovering — the

ref

values are required for all interaction tools.

browser_snapshot

会返回包含每个可交互元素

ref

值的无障碍树。你必须在点击、输入或悬停操作前生成快照——所有交互工具都需要用到

ref

值。

Critical: Output Size Awareness

重要提示：注意输出大小

Tool	Output Size	Notes
`browser_snapshot`	Medium-Large	Full accessibility tree — scales with page complexity
`browser_take_screenshot`	Large	Base64 image — use sparingly
`browser_console_messages`	Variable	Can be very large on noisy apps
`browser_network_requests`	Variable	Can be very large on API-heavy pages
`browser_navigate`	Small	Returns page title only
`browser_click`	Small	Returns snapshot after click
`browser_type`	Small	Returns snapshot after typing

Prefer

browser_snapshot

over

browser_take_screenshot

for understanding page structure. Screenshots are for visual verification only.

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

如需了解页面结构，优先使用

browser_snapshot

而非

browser_take_screenshot

，截图仅用于视觉验证。

Workflow 1: Navigate & Inspect

工作流1：访问与检查

Trigger: User says "open this page", "what's on the page?", "inspect the UI", "check the layout"

触发场景：用户说「打开这个页面」、「页面上有什么？」、「检查UI」、「查看布局」

Steps

步骤

Navigate to the page:

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

Get page structure (always do this before interacting):

browser_snapshot → accessibility tree with ref values for all elements

Analyze the snapshot: Identify interactive elements (buttons, links, inputs) by their
```
ref
```
values. Report page structure to user.

访问目标页面：

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

获取页面结构（交互前必须执行）：

browser_snapshot → 包含所有元素ref值的无障碍树

分析快照： 通过
```
ref
```
值识别可交互元素（按钮、链接、输入框），向用户反馈页面结构。

Decision: Snapshot vs Screenshot

决策：快照 vs 截图

Need	Use
Understand page structure, find elements	`browser_snapshot` (structured, has `ref` values)
Visual appearance, layout bugs, CSS issues	`browser_take_screenshot` (visual image)
Both structure and appearance	Snapshot first, then screenshot if visual check needed

需求	使用工具
了解页面结构、查找元素	`browser_snapshot` （结构化，含 `ref` 值）
查看视觉效果、布局bug、CSS问题	`browser_take_screenshot` （可视化图片）
同时需要结构和外观	先拍快照，如需视觉检查再截图

Workflow 2: Form Interaction

工作流2：表单交互

Trigger: User says "fill out the form", "submit the login", "type in the field", "select an option"

触发场景： 用户说「填写表单」、「提交登录」、「在输入框输入内容」、「选择选项」

Steps

步骤

Snapshot to find form fields:

browser_snapshot → identify input refs and their labels

Fill fields (choose based on complexity):

Single field:

browser_type({ ref: "input-ref", text: "value" })

Multiple fields:

browser_fill_form({ fields: [{ ref: "ref1", value: "val1" }, { ref: "ref2", value: "val2" }] })

Dropdown:

browser_select_option({ ref: "select-ref", values: ["option-value"] })

Submit the form:

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

Verify result:

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

快照查找表单字段：

browser_snapshot → 识别输入框ref及其标签

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

单字段：

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"] })

提交表单：

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

验证结果：

browser_snapshot → 检查成功提示、错误状态或页面跳转

Key Patterns

核心模式

```
browser_fill_form
```
is faster than multiple
```
browser_type
```
calls for multi-field forms
Use
```
browser_press_key({ key: "Enter" })
```
as alternative to clicking submit
After submission, wait if needed:
```
browser_wait_for({ text: "Success" })
```
then snapshot

多字段表单使用
```
browser_fill_form
```
比多次调用
```
browser_type
```
更快
可以用
```
browser_press_key({ key: "Enter" })
```
替代点击提交按钮
提交后如需等待：执行
```
browser_wait_for({ text: "Success" })
```
后再生成快照

Workflow 3: Debug Investigation

工作流3：调试排查

Trigger: User says "debug the page", "check for errors", "what API calls are happening?", "why isn't it working?"

触发场景： 用户说「调试页面」、「检查错误」、「正在调用什么API？」、「为什么它不工作？」

Steps

步骤

Navigate to the problematic page:
```
browser_navigate({ url: "..." })
```

Run these in parallel (they are independent):

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

Snapshot the page:

browser_snapshot → current UI state, error messages, loading states

Investigate further:

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

访问有问题的页面：
```
browser_navigate({ url: "..." })
```

并行运行以下工具（相互独立）：

browser_console_messages → JavaScript错误、警告、日志
browser_network_requests → API调用、失败请求、状态码

生成页面快照：

browser_snapshot → 当前UI状态、错误信息、加载状态

进一步排查：

browser_evaluate({ expression: "document.querySelectorAll('.error').length" }) → 运行自定义JS

Workflow 4: Multi-Step Navigation

工作流4：多步骤导航

Trigger: User says "go through the flow", "test the signup process", "walk through the wizard"

触发场景： 用户说「走完流程」、「测试注册流程」、「遍历引导流程」

Steps

步骤

Navigate to starting page:
```
browser_navigate({ url: "..." })
```

For each step:

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

Handle dialogs if they appear:

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

Go back if needed:
```
browser_navigate_back
```

访问起始页面：
```
browser_navigate({ url: "..." })
```

逐个完成步骤：

browser_snapshot → 找到下一步操作
browser_click({ ref: "..." }) 或 browser_type({ ref: "...", text: "..." })
browser_wait_for({ text: "expected content" }) → 页面异步加载时使用

处理弹出的对话框：

browser_handle_dialog({ accept: true }) → 确认/告警/提示框

如需返回上一页：
```
browser_navigate_back
```

Tool Reference

工具参考

Navigation

导航类

Tool	Purpose	Parameters
`browser_navigate`	Go to URL	`url` (required)
`browser_navigate_back`	Go back	None
`browser_wait_for`	Wait for text or time	`text` or `timeout` (ms)
`browser_tabs`	List/switch tabs	None or `index` to switch

工具	用途	参数
`browser_navigate`	访问指定URL	`url` （必填）
`browser_navigate_back`	返回上一页	无
`browser_wait_for`	等待指定文本出现或等待指定时长	`text` 或 `timeout` （毫秒）
`browser_tabs`	列出/切换标签页	无或指定切换的 `index`

Inspection

检查类

Tool	Purpose	Parameters
`browser_snapshot`	Accessibility tree with refs	None
`browser_take_screenshot`	Visual screenshot	None
`browser_console_messages`	JS console output	None
`browser_network_requests`	Network activity	None

工具	用途	参数
`browser_snapshot`	获取含ref值的无障碍树	无
`browser_take_screenshot`	获取可视化截图	无
`browser_console_messages`	获取JS控制台输出	无
`browser_network_requests`	获取网络活动记录	无

Interaction

交互类

Tool	Purpose	Parameters
`browser_click`	Click element	`ref` (from snapshot)
`browser_type`	Type text	`ref` , `text`
`browser_fill_form`	Fill multiple fields	`fields` array of `{ ref, value }`
`browser_select_option`	Select dropdown	`ref` , `values` array
`browser_hover`	Hover element	`ref`
`browser_drag`	Drag and drop	`startRef` , `endRef`
`browser_press_key`	Keyboard input	`key` (e.g., "Enter", "Tab")
`browser_file_upload`	Upload file	`ref` , `paths` array
`browser_handle_dialog`	Confirm/dismiss dialog	`accept` boolean

工具	用途	参数
`browser_click`	点击元素	`ref` （来自快照）
`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` 布尔值

Advanced

高级功能

Tool	Purpose	Parameters
`browser_evaluate`	Run JavaScript	`expression`
`browser_resize`	Resize viewport	`width` , `height`
`browser_close`	Close page	None
`browser_install`	Install browser	None
`browser_run_code`	Run Playwright code	`code` string

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

Troubleshooting

故障排查

"No browser running" or Connection Errors

「无浏览器运行」或连接错误

The Playwright MCP server manages its own browser instance. If tools fail:

Try
```
browser_install
```
to ensure the browser binary is available
Try
```
browser_navigate
```
to a simple URL — this may initialize the browser

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

尝试运行
```
browser_install
```
确保浏览器二进制文件可用
尝试用
```
browser_navigate
```
访问一个简单URL——这可能会初始化浏览器

Elements Not Found After Navigation

导航后找不到元素

Pages with async content may not have rendered yet:

Use

browser_wait_for({ text: "expected content" })

before snapshot

Use
```
browser_wait_for({ timeout: 2000 })
```
for time-based waiting

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

快照前使用

browser_wait_for({ text: "expected content" })

使用
```
browser_wait_for({ timeout: 2000 })
```
进行基于时间的等待

Proxied or Internal Domains

代理或内部域名访问失败

The MCP browser cannot reach proxied or internal domains that require network tunnels. Use

http://127.0.0.1:54321

directly for local Supabase.

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

http://127.0.0.1:54321

。

Snapshot Returns Very Large Output

快照返回输出过大

Complex pages produce large accessibility trees. If output is too large:

Navigate to a specific sub-page rather than the full app
Use
```
browser_evaluate
```
to query specific elements instead

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

访问特定子页面而非整个应用
使用
```
browser_evaluate
```
查询特定元素即可