教程2026-11-16 · 智涌AI

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

playwright-cli 教程头图:左侧大字「playwright-cli 浏览器命令行」与 v0.1.24 11 月 10 日发布、15,228 星 Apache-2.0、无头会话空闲 1 小时退出三张数据卡;右侧终端依次显示全局安装 @playwright/cli、安装 Skill、打开 TodoMVC 示例、输入待办、用快照引用 e21 勾选、按回车,并把快照保存为 yml 文件

让 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 + SkillPlaywright 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,命令和配置项可能继续调整。

前置条件

第一步:安装 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 }
}

README 还特别提醒:有些页面会通过实验性的 WebMCP 接口给 Agent 注册工具,这些工具的名称、描述、schema 和返回结果都来自页面,属于不可信输入,不能当指令执行。

第五步:把结果交还给你

让 Agent 测完一个流程后留下证据:成功和失败场景各截一张图(README 的演示提示词就是这么写的),需要时 video-start/video-stop 录一段,Skill 里的 PR 附件文档讲了怎么用 gh 把截图和视频附到 PR 上。录下的操作可以用 recording-stop 转成 Playwright 测试代码,下次直接进 CI。

常见坑

浏览器工具怎么挑、钱花在哪,可以看站内 Agent 浏览器工具成本对比;同类的命令行方案有 agent-browser;要把浏览器关进沙箱,参考 Playwright 浏览器沙箱配置。

做到哪一步算完成

最后

挑一个你最近手动点过三遍以上的本地页面流程,让 Agent 用 playwright-cli 走一遍并截图,最后用 recording-stop 导出代码,存成第一条 Playwright 测试。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。