Playwright+MCP+Agent Browser：AI驱动的Web自动化实战指南

近几年做 Web 自动化，Playwright 基本已经成了我的第一选择。相比旧一代方案，它内置了自动等待、多浏览器支持、录制生成脚本和完整的测试报告链路，配合 MCP 之后还能让 Claude Code、Codex 这类 AI 编程工具直接驱动浏览器，是打通“AI 主导 Web 自动化”这条路径的关键拼图。这篇文章会把 Playwright 的 CLI、MCP、Agent Browser 三条主线完整拆一遍：先讲清楚它们各自解决什么问题，再给环境配置、最小示例、参数说明和常见报错。适合正在做 UI 自动化测试、准备把 AI 助手接入浏览器操作，或者想从 Selenium 迁移过来的人。

1. 先搞清楚 Playwright 在 AI 自动化里扮演什么角色

1.1 三个关键概念：CLI、MCP、Agent Browser

Playwright 是一个跨浏览器自动化框架，支持 Chromium、Firefox、WebKit。这是它区别于 Selenium 的核心点——Selenium 需要为每个浏览器下载对应驱动，还要处理版本匹配，很多人搜“selenium 浏览器驱动怎么判断下载哪个区别”，本质就是旧方案里最常踩的坑。Playwright 把这层复杂度收掉了，安装时统一下载浏览器二进制，不需要单独找驱动。

CLI 是 Playwright 提供的命令行工具，用来安装浏览器、录制脚本、运行测试、查看报告。MCP 是 Model Context Protocol 的缩写，是一套让 AI 模型与外部工具通信的开放协议。Playwright 官方提供了@playwright/mcp这个 MCP 服务器，AI 工具通过它可以执行打开页面、点击、输入、截图、读取 DOM 等操作。Agent Browser 不是一个具体产品，而是“AI Agent 自主控制浏览器执行多步任务”的实践思路，底层引擎仍然离不开 Playwright。

这三者的关系可以这样看：CLI 方便人类开发者高效操作 Playwright，MCP 让 AI 工具能以标准协议调用 Playwright，Agent Browser 是最终表现形式——AI 读取页面、判断动作、点击按钮、填写表单，完成一整条任务链。

1.2 为什么它适合 AI 主导的自动化

传统 UI 自动化最花时间的地方，是把测试步骤翻译成代码。Playwright 的 codegen 能把人工点击录制为脚本，已经省了第一步。MCP 接入后，AI 能根据自然语言指令直接生成动作并执行，等于把“写脚本”和“跑脚本”合并成了“描述任务，AI 操作”。

但这里要泼一盆冷水：AI 操作浏览器目前更适合验证性任务、探索性测试和数据处理，离完全替代人工编写稳定用例还有距离。原因不是模型能力不够，而是页面变化、元素定位、断言稳定性这些工程问题，AI 一样会踩。理解了这层边界，后面用 CLI、MCP、Agent Browser 时才不会期待错方向。

2. 先把环境跑通：安装、浏览器、第一个脚本

2.1 环境准备和依赖选择

Playwright 支持 Node.js 和 Python 两套生态。做测试框架选 Node.js 的更多，因为@playwright/test自带断言、夹具和报告器，TypeScript 支持也好。如果团队本身就是 Python 技术栈，用 Python 版pytest-playwright完全够用。下面是两种安装路径，按你当前环境选择即可。

Node.js 环境：

npm init -y npm i -D @playwright/test npx playwright install

Python 环境：

pip install pytest-playwright playwright install

npx playwright install会下载 Chromium、Firefox、WebKit 三个浏览器。网络慢的话可以按需安装，比如只装 Chromium：

npx playwright install chromium

最容易忽略的是系统依赖。Linux 服务器上跑无头浏览器，经常要额外装系统库，用npx playwright install-deps可以一次性补齐。Windows 上不需要这一步，macOS 一般也不需要。

2.2 第一个最小脚本

装完环境后，写一个最小脚本确认链路。Node.js 版本：

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://example.com'); console.log(await page.title()); await browser.close(); })();

Python 版本：

from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page() page.goto("https://example.com") print(page.title()) browser.close()

能输出页面标题，说明环境没问题。很多人卡在启动报错，出现类似Executable doesn't exist的信息，基本就是浏览器二进制没下载完整，重新执行npx playwright install即可。

2.3 环境正常的判断标准

不要急着写复杂用例。先确认三件事：

1. 浏览器能启动，headless 和 headed 两种模式都试一下。
2. 页面能正常打开，title 能取到。
3. 关闭方法能执行，进程不残留。

这三条都过了，Playwright 本身没问题。后续如果还报错，问题大概率在脚本逻辑、页面结构或网络环境，而不是框架安装。

3. CLI 实战：从录制到批量执行

3.1 codegen：把人工操作变成脚本

Playwright CLI 里最值得先用的命令是 codegen：

npx playwright codegen https://example.com

运行后会打开一个浏览器窗口和一个代码生成面板。你在页面上的点击、输入、跳转、滚动，都会被实时转换成 Playwright 脚本，支持 JavaScript、TypeScript、Python、Java 几种语言。很多人搜“UI 自动化录制生成脚本的开源项目”，Playwright codegen 就是最典型的答案，而且它内置在官方工具链里，不用额外装插件。

录制生成脚本适合快速搭建测试骨架，但不建议直接当作稳定用例。录制出来的选择器有时带很长的层级路径，页面一改就挂。我的做法是：把录制结果当第一版，然后把核心元素换成文本选择器或>npx playwright test

默认查找tests目录下的.spec.js或.spec.ts文件。常用参数：

# 打开浏览器界面运行 npx playwright test --headed # 控制并发 worker 数量 npx playwright test --workers=2 # 只跑某个文件 npx playwright test tests/login.spec.ts

配置文件playwright.config.ts里要关注这几个核心参数：

3.3 报告和调试

跑完测试后查看报告：

npx playwright show-report

失败用例建议先看 trace。Playwright 默认可以记录页面操作快照，失败时能回放每一步的 DOM 状态。判断是脚本问题还是页面问题时，trace 比截图有效得多。

还有一个调试模式：

npx playwright test --debug

会在每个 action 前暂停，配合开发者工具逐步检查元素状态。遇到“点击了但没反应”“断言失败但页面看起来正常”这类问题时，这个模式能直接看出动作执行前元素是否可交互。

4. MCP 接入：让 AI 编程工具直接驱动浏览器

4.1 MCP 解决什么问题

MCP 全称 Model Context Protocol，是让 AI 模型与外部工具通信的开放协议。现在很多 AI 编程工具都在支持 MCP，热词里大量出现的“mcp server”“mcp协议”“codex cli”“claude code cli”都和这条技术路线有关。Playwright 官方提供了@playwright/mcp这个 MCP 服务器，让 AI 工具可以直接调用浏览器操作能力。

没有 MCP 之前，想让 AI 帮你操作浏览器，得自己写脚本、自己封装接口、自己处理对话流程。有了 MCP，AI 编程工具原生就能打开页面、点击按钮、读取内容，你只需要用自然语言描述任务。

4.2 安装和配置 @playwright/mcp

先全局安装：

npm i -g @playwright/mcp

确认本机浏览器可用：

npx playwright install chromium

然后在 AI 编程工具里配置 MCP server。不同工具的配置格式不同，但通用思路是加一个stdio类型的 MCP server，命令指向@playwright/mcp。常见配置项大致是这样：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }

不同工具的配置入口和文件路径并不统一，原始资料也没有给出统一标准，建议以你正在使用的 AI 工具官方文档为准。配置完重启工具，AI 助手就能识别到 playwright 相关的工具接口。

4.3 接上 MCP 后能做什么

实际使用中，比较典型的任务类型有：

1. 让 AI 打开一个页面，读取正文内容，帮你整理产品信息。
2. 让 AI 在本地测试环境完成注册、登录、表单填写。
3. 让 AI 截取页面关键区域，分析布局是否异常。
4. 让 AI 遍历页面上的链接，检查是否存在失效跳转。

这些任务本质还是 Playwright 的能力，MCP 只是把接口暴露给 AI。判断 MCP 是否配置成功，最快的方式就是让 AI 打开一个页面并读取标题，能正常返回就说明链路通了。

4.4 使用时的注意事项

AI 通过 MCP 操作浏览器，最常见的两个坑。

第一个是页面加载慢。AI 发出点击指令时元素还没出现，需要在 MCP 配置里调长超时时间，或者让 AI 先执行等待动作再操作。第二个是复杂页面定位不准，尤其是 Canvas、Shadow DOM、跨域 iframe 里的元素，普通选择器不好用。遇到这种情况，我一般先手动跑一遍 codegen，确认选择器能稳定定位到，再让 AI 执行。

另外要注意权限和接口边界。MCP 暴露的能力越强，越要明确它能访问哪些页面、操作哪些环境。不要让 AI 工具拿着默认配置去访问生产环境，最好限定在本地测试地址或明确的测试环境里。

5. Agent Browser 的落地思路

5.1 从录制脚本到 AI 自主执行

Agent Browser 是 AI 自动化里很热的方向，核心思路是让 AI Agent 把“打开页面、查找目标、点击操作、读取结果”完整走完，而不是只执行一段写死的脚本。热词里有人问“computer use 和 MCP 的区别”，可以这样理解：computer use 是从屏幕视觉层面操作整台电脑，粒度粗、反馈慢；MCP 是协议层的工具调用；Playwright 属于精确操作通道，定位准确、执行快、结果可验证。三者不是替代关系，而是不同层级的自动化手段。

5.2 一种可行的组合方案

真实项目里实现 Agent Browser，不一定需要引入重量级 Agent 框架。用一条业务循环就可以把 Playwright 和 LLM 结合起来：

打开页面 -> 抓取页面文本和可操作元素 -> 交给 LLM 判断下一步 -> 执行点击或输入 -> 继续读取页面 -> 循环，直到目标完成或达到最大步数

这种方案的好处是过程透明。每一步都能看到 AI 的判断依据和实际动作，出了问题能定位到具体环节。坏处是页面越复杂，token 消耗和误判率越高，所以更适合把任务拆成小目标，不要一口气让 AI 完成太多步骤。

5.3 一个最小流程示例

假设要实现“打开测试站点，搜索关键词，读取搜索结果”的小 Agent：

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://example.com'); const text = await page.locator('body').innerText(); // 将 text 传给 LLM，由模型返回动作描述，例如 { type: 'click', selector: '#search-button' } // 这里省略具体 LLM 调用代码，不同模型接口不同 await page.click('#search-button'); await page.waitForLoadState('networkidle'); const results = await page.locator('.result').allInnerTexts(); console.log(results); await browser.close(); })();

这段代码重点不是 LLM 调用本身，而是让你理解“读取页面 -> 模型决策 -> 执行动作 -> 再次读取”的循环结构。在此基础上，可以逐步加入步数上限、异常恢复、结果校验，就变成了一个可用的轻量 Agent。

5.4 适用场景和边界

Agent Browser 当前最适合探索性任务和一次性任务：快速调研、数据核对、页面信息整理、测试数据生成。它还不适合当作稳定回归测试的替代方案，因为 AI 每次判断可能不完全一致，结果不可重复，这在自动化测试里是硬伤。正式回归用例，建议还是用固定的 Playwright 脚本，日常探索性验证再交给 Agent 组合。

6. 元素定位、高频报错与排查链路

6.1 元素定位优先级

看到热词里有人搜“playwright 定位 span”“playwright 定位元素方法大全”，这里给一份通用的定位选择顺序：

1. 文本定位：page.getByText('登录')
2. 角色定位：page.getByRole('button', { name: '提交' })
3. 标签定位：page.getByLabel('用户名')
4. placeholder 定位：page.getByPlaceholder('请输入手机号')
5. testid 定位：page.getByTestId('submit-btn')

这个顺序不是随意排的。从可读性和稳定性来看，语义化定位优先于 CSS 选择器。CSS 路径太长太脆，页面改版很容易挂。建议项目里给核心交互元素加上>const frame = page.frameLocator('iframe[src="..."]'); await frame.locator('.content').click();

iframe 内容没加载完是定位失败的常见原因。切进 iframe 之后，先等内部元素出现，再执行操作。很多时候不是选择器写错了，而是 iframe 还没渲染完成。

7. 整体建议与避坑清单

7.1 先定边界，再谈自动化

不要用 Playwright 去处理不属于测试或正当自动化范畴的事情。它对正常业务系统的测试、调试、数据采集和 AI 辅助验证都很有帮助。但如果目标是对抗网站风控策略，那不是这个工具的设计用途，也不应该成为实践方向。把使用边界定清楚，后面所有方案都围绕“自己的项目、明确的测试环境、合规的验证需求”展开，才不会走偏。

7.2 从最小样例开始，别急着上全套

装完环境，先跑一个打开页面取标题的脚本，确认基础链路通了，再接触 MCP 和 Agent。很多人在环境没确认的情况下直接配 MCP，报错之后分不清是浏览器问题、网络问题还是协议配置问题。这个排查成本一开始就能避免。

如果只是学习，默认配置加上 codegen 就能玩明白。如果要长期维护用例，那就要把超时时间、失败重试、trace、元素定位规范这些工程问题提前定好，而不是等项目跑了两百条用例之后再回头补。

7.3 稳定性和日志比“能跑通”更重要

自动化任务不是“能跑就行”，连续跑 100 次还能稳定通过，才算合格。建议在配置里打开 trace，失败时保留页面快照：

use: { trace: 'on-first-retry', screenshot: 'only-on-failure', }

日志和输出目录也要提前规划。批量任务如果只输出到一个目录，跑多了根本分不清哪次是哪个版本。按时间戳或任务 ID 组织输出，排查问题会轻松很多。

7.4 排查问题有固定顺序

遇到问题不要一上来就调参数。我的排查顺序是：

1. 先看现象：报错、卡住、无输出，还是输出异常。
2. 再看输入：URL 是否正确、文件格式对不对、路径有没有权限。
3. 再看环境：依赖版本、浏览器是否完整安装、磁盘空间和内存占用。
4. 再看参数：并发数、批量数、超时时间、重试次数是否合理。
5. 最后才怀疑工具本身：查版本兼容性和已知限制。

多数“奇怪问题”都不是工具能力不够，而是前置环境和输入材料没有处理干净。踩过几次之后你会发现，Playwright 真正帮你省下的时间，不只是写脚本的时间，而是把安装、录制、执行、报告、调试、AI 接入全链路打通之后，你可以把精力放在真正需要判断的测试场景上。