playwright-cli 怎么用:让编程 Agent 用命令行开浏览器

让 Claude Code、Copilot 这类编程 Agent 测网页,常见做法是接 Playwright MCP,代价是每一步都把一大段页面结构塞进上下文。微软开源的 playwright-cli 换了个做法:把浏览器操作做成一条条 shell 命令,再配一个 Skill 告诉 Agent 怎么用,页面快照默认存成文件,模型要看再去读。11 月 10 日发布的 v0.1.24 还加了「后台接管已登录浏览器」。这篇按官方 README、Skill 文件和发布说明,把安装、会话、快照、配置和容易踩的坑整理成五步。
CLI 和 MCP 的分工,README 写得很直白
README 开头就给了建议:用编程 Agent,选 CLI。理由是 CLI 调用更省 token,不用把一大份工具 schema 和冗长的无障碍树装进上下文,Agent 可以在同一个窗口里兼顾浏览器、代码库、测试和推理。MCP 留给需要持续状态、反复审视页面结构的场景,例如探索式自动化、自愈测试、长时间运行的自主流程。
| 对比项 | playwright-cli + Skill | Playwright MCP |
|---|---|---|
| 调用方式 | Agent 跑 shell 命令 | Agent 调 MCP 工具 |
| 页面信息 | 快照写成 yml 文件,按需读取或 find 搜索 | 工具结果直接进上下文 |
| 适合 | 写代码、跑测试顺带操作浏览器 | 长时间、强依赖页面状态的自动化 |
| 接入 | npm install -g + install --skills | 在 Agent 里配置 MCP 服务器 |
项目信息(GitHub API 与 npm,2026-11-16 北京时间查询):仓库 microsoft/playwright-cli,Apache-2.0 许可,15,228 星;最新版 v0.1.24 发布于北京时间 11 月 10 日 09:16,依赖 Playwright 1.66 alpha;npm 包 @playwright/cli 在 11 月 9 日到 15 日一周下载 1,836,719 次。版本号还在 0.1,命令和配置项可能继续调整。
前置条件
- Node.js 20 或更新版本(README 写的要求)。
- 一个会执行 shell 命令的编程 Agent:README 点名 Claude Code、GitHub Copilot,其他 Agent 也行。
- 项目里已经装了 Playwright 1.59 或更新版本的,可以直接用
npx playwright cli,不必全局安装。
第一步:安装 CLI 和 Skill
npm install -g @playwright/cli@latest
playwright-cli --help
playwright-cli install --skills
install --skills 把 Skill 装到本地,Claude Code、Copilot 等会读取。Skill 的 frontmatter 把可用工具限定为 Bash(playwright-cli:*) 和 npx playwright 两类命令,主文件之外还带 10 份参考文档,覆盖跑和调试 Playwright 测试、请求 mock、存取 cookie 与 localStorage、生成测试、trace、录视频、把截图和视频附到 PR 等任务。
不装 Skill 也能用。README 给的办法是直接在提示词里让 Agent 先看帮助:
Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.
第二步:用快照引用操作页面
每条命令执行完,CLI 都会给出当前页面状态,快照存到 .playwright-cli/ 下的 yml 文件里,元素带上 e21 这样的引用。Agent 拿引用去点、去填,比自己拼选择器稳。手动跑一遍官方示例:
playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot
默认无头运行,加 --headed 才能看到窗口。页面大的时候别整页抓,几个参数能少读很多内容:
playwright-cli snapshot --depth=4 # 先看浅层结构
playwright-cli snapshot e34 # 再展开某个元素
playwright-cli find "Add to cart" # 搜快照,返回匹配节点和上下 3 行
playwright-cli --raw eval "document.title" # 只要结果,不要页面状态和生成代码
除了引用,也接受 CSS 选择器和 Playwright 定位器,比如 playwright-cli click "getByRole('button', { name: 'Submit' })"。常用的还有 console、requests 看控制台和网络请求,route mock 接口,tracing-start/tracing-stop 录 trace,recording-stop 把录下的操作输出成 Playwright 代码。
快照存成文件、需要时再搜,Agent 才不会每走一步都把整页无障碍树读一遍。
第三步:用会话把项目隔开
浏览器配置默认放在内存里,同一会话内多次调用保留 cookie 和存储,浏览器一关就没了。要跨重启保留登录态,加 --persistent。不同项目用 -s=名字 分开:
playwright-cli -s=shop open https://example.com --persistent
playwright-cli list # 列出所有会话
playwright-cli close-all # 关闭全部浏览器
PLAYWRIGHT_CLI_SESSION=todo-app claude . # 让这次 Claude Code 默认用 todo-app 会话
Agent 在后台跑浏览器时,playwright-cli show 会打开一个面板:网格视图按工作区列出所有会话的实时画面、网址和标题;点进某个会话可以接管鼠标键盘,按 Esc 交还。
v0.1.24 的重点是接管你已登录的浏览器而不抢屏幕:通过 Playwright 浏览器扩展连接,加 PLAYWRIGHT_MCP_BACKGROUND=1,被控标签页和窗口留在后台;配置里写 "tabGroup": false,扩展会话就不会给 Chrome 新建标签组。
PLAYWRIGHT_MCP_BACKGROUND=1 playwright-cli attach --extension=chrome
第四步:用配置文件收紧权限
CLI 默认读 .playwright/cli.config.json,也可以用 --config 指定。给 Agent 用,建议至少写上允许访问的域名:
{
"browser": {
"browserName": "chromium",
"contextOptions": { "locateOnlyVisible": true }
},
"network": {
"allowedOrigins": ["http://127.0.0.1:3000"]
},
"outputDir": ".playwright-cli",
"timeouts": { "action": 5000, "navigation": 60000 }
}
allowedOrigins/blockedOrigins:默认全部放行;同时命中两边的按拦截处理。allowUnrestrictedFileAccess:默认 false,上传文件只能来自 MCP roots 范围内的路径,别随手打开。timeouts:动作默认 5,000 毫秒,导航默认 60,000 毫秒。locateOnlyVisible:v0.1.24 新增,需手动开启,定位器只匹配可见元素。
README 还特别提醒:有些页面会通过实验性的 WebMCP 接口给 Agent 注册工具,这些工具的名称、描述、schema 和返回结果都来自页面,属于不可信输入,不能当指令执行。
第五步:把结果交还给你
让 Agent 测完一个流程后留下证据:成功和失败场景各截一张图(README 的演示提示词就是这么写的),需要时 video-start/video-stop 录一段,Skill 里的 PR 附件文档讲了怎么用 gh 把截图和视频附到 PR 上。录下的操作可以用 recording-stop 转成 Playwright 测试代码,下次直接进 CI。
常见坑
- 引用过期。页面一变,旧快照里的
e21就可能指向别的元素或不存在。让 Agent 在关键操作前重新snapshot或find,别拿很早以前的引用去点。 - 会话一小时后自己关了。无头会话一小时没有命令就自动退出,有头浏览器不受影响。长任务用
open --idle-timeout=<毫秒>调整,传 0 关闭超时。 - 隐藏的重复元素触发严格模式报错。页面缓存了一份隐藏的同名按钮时,定位器会匹配到多个。v0.1.24 起在配置里开
locateOnlyVisible。 - 删错会话数据。v0.1.24 之前,
-s=work delete-data会连work-test的持久配置一起删,新版已限定为精确匹配。老版本先升级再清理。 - 接管日常浏览器的风险。
attach --extension让 Agent 用你的登录态,能看到的东西和你一样多。只给它开需要的标签页,或者单独建一个--persistent会话专门登录测试账号。
浏览器工具怎么挑、钱花在哪,可以看站内 Agent 浏览器工具成本对比;同类的命令行方案有 agent-browser;要把浏览器关进沙箱,参考 Playwright 浏览器沙箱配置。
做到哪一步算完成
playwright-cli --help能正常输出,Skill 已装进你用的 Agent。- Agent 能按提示词在 TodoMVC 示例上走完添加、勾选流程,并留下截图。
- 项目根目录有
.playwright/cli.config.json,allowedOrigins只放了要测的地址。 - 不同项目用不同
-s会话,playwright-cli list能看到它们。
最后
挑一个你最近手动点过三遍以上的本地页面流程,让 Agent 用 playwright-cli 走一遍并截图,最后用 recording-stop 导出代码,存成第一条 Playwright 测试。