沉淀园

Playwright CLI 方案详解

Properties1
tagsai, playwright, 自动化, 测试

14分钟阅读

一句话简介：AI Agent 用命令行驱动浏览器做 UI 自动化的官方方案——本页是它的操作手册（命令面 + 会话模型 + 安装落地），横向选型对比见 AI浏览器自动化框架对比。

定位：官方怎么看 CLI vs MCP

微软在 microsoft/playwright-cli README 中的正式定位（2026-09 查证）：

CLI: Modern coding agents increasingly favor CLI-based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas and verbose accessibility trees into the model context… better suited for high-throughput coding agents.

MCP remains relevant for specialized agentic loops that benefit from persistent state, rich introspection, and iterative reasoning over page structure, such as exploratory automation, self-healing tests, or long-running autonomous workflows.

即：编码 Agent 日常干活用 CLI+Skills；需要持续浏览器状态的探索式/自愈/长时自主任务才用 MCP。分工，不是替代。

⚠️ 包名已迁移：npm 包 playwright-cli（0.262.0）已弃用，提示改用 @playwright/cli（2026-09 时为 0.1.x，版本尚早）。仓库 microsoft/playwright-cli 13.4K star，活跃维护。

三层结构与核心循环

Agent（ZCode / Claude Code / Copilot…）
   ↓  读 Skill 学会命令组合（工作流知识在 Skill 层）
playwright-cli（@playwright/cli）
   ↓  无障碍树快照 + ref 系统
Playwright 引擎（Chromium / Firefox / WebKit）

每一步的循环是：snapshot 拿快照（元素带 e15 这样的 ref）→ click e15 / fill e5 "文字" 操作 → 再 snapshot 验证结果。

与视觉路线的本质区别（来源：AI浏览器回归测试Passmark实测 之外的 Raina 实战文，见原始素材）：不是截图+多模态识别，而是 DOM 解析一次生成、后续复用——秒级完成；视觉路线（Midscene）一个用例要几分钟。视觉路线的价值在 Canvas/shadow DOM/跨域 iframe 等无障碍树拿不到节点的场景，两条路线互补（AI 分析）。

命令面速查（经 npx @playwright/cli --help 实测，2026-09-19）

核心操作

playwright-cli open [url] [--headed]     # 开浏览器（默认无头）
playwright-cli goto <url>
playwright-cli snapshot [--depth=N]      # 拿无障碍树快照与元素 ref
playwright-cli find "登录"               # 快照内按文本/正则搜元素，免全量快照
playwright-cli find --regex "/sign (in|up)/i"
playwright-cli click e15 / dblclick / hover / check / uncheck
playwright-cli fill e5 "user@x.com" --submit   # --submit = 填完按回车
playwright-cli select e9 "option" / upload ./f.pdf / drag e2 e8
playwright-cli eval "el => el.getAttribute('data-testid')" e5
playwright-cli dialog-accept / dialog-dismiss / resize 1280 800

会话管理

playwright-cli -s=项目A open https://x.com --persistent   # 命名会话 + 登录态落盘
playwright-cli list / close-all / kill-all
PLAYWRIGHT_CLI_SESSION=todo-app claude .   # 环境变量绑定会话
  • 默认内存 profile：cookie 在多次 CLI 调用间保留，浏览器关闭即丢；--persistent 落盘跨重启。
  • 无头会话空闲 1 小时自动关；open --idle-timeout=<ms> 可调，0 为禁用。

登录态与存储

playwright-cli state-save auth.json / state-load auth.json   # 导出/导入登录态
playwright-cli cookie-list / cookie-get / cookie-set / cookie-clear
playwright-cli localstorage-list / get / set / delete / clear   # sessionStorage 同理

DevTools 与流程固化

playwright-cli console / requests / request <n>          # 排查：控制台与网络
playwright-cli tracing-start / tracing-stop              # trace 记录
playwright-cli recording-start / recording-stop          # 人工点一遍 → 自动转 Playwright 代码
playwright-cli run-code <code> / --filename=f
playwright-cli screenshot [--hires] / pdf / video-start --cursor

recording-start/stop 是”codegen 是草稿不是规格”工作流的官方实现：先人工录一遍拿代码草稿，再整理成正式 spec。

监控与其他

playwright-cli show            # 可视化仪表盘：所有 Agent 会话实时屏幕直播，可鼠标接管
playwright-cli route '**/*.png' abort / route-list / unroute   # mock 网络请求
playwright-cli set-color-scheme dark / 移动设备模拟（Pixel/iPhone）
playwright-cli webmcp-list / webmcp-call <name>   # 页面自注册工具（实验性 WebMCP）

官方 README 专门标注：WebMCP 的工具名、描述、schema 均来自页面，属不可信输入而非指令——与库内”raw 素材不可信”同一防线（见 Harness工程与AGENTS-md实践）。

Skill 层

  • 官方 skill：skills.sh 上 microsoft/playwright-cli@playwright-cli 约 159K 安装，playwright 类第一。内容 484 行：全命令、快照最佳实践、表单提交/多标签/DevTools 调试三个完整示例，allowed-tools 白名单只授权 Bash 调 playwright-cli。
  • 安装方式：playwright-cli install --skills（装本地后 Claude Code/Copilot 等自动使用）；也可走 skills.sh。另有 Skills-less operation：不装 skill，直接让 Agent 读 playwright-cli --help 自学。
  • 社区工作流封装（Raina 实战文）：三主 skill + 一辅助——页面探索与用例生成（输出 JSON 用例）、用例执行与中断记录、脚本自愈（识别错误元素→重新快照→改 ref→重跑）、json→excel 可视化转换（供评审）。自带简单验证码识别，复杂验证码暂停交人。
  • 三级效率阶梯在此方案的表现：AI 自由探索耗 41% 上下文 → 沉淀成 Skill 后 5% → 固定流程 run-code 脚本化 0 token（数据来源见 AI浏览器自动化框架对比）。

安装落地

npm install -g @playwright/cli@latest
npx playwright install chromium          # 浏览器二进制约 150MB
# 国内镜像：PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
playwright-cli install --skills          # 可选：装官方 skill
  • Windows 下 URL 含 & 需加引号（官方 SKILL.md 专门提示）。
  • 登录态优先 --persistent 或 state-save/load；涉及密码时用环境变量填充，凭证永远不经过模型（模式同 Stagehand，见 RPA浏览器自动化实操方法）。
  • 平台适配坑（小红书 HTTPS 拒 localhost 图、掘金 CodeMirror 异步加载等）：每个目标页面独立适配，Skill 不做通用模板（经验来源见 AI浏览器自动化框架对比）。

AI 分析

在本知识库环境中的用法是——由 Agent 通过 Bash 直接驱动 playwright-cli（skill 教的正是这个路径），配合 show 仪表盘人工监督。适合确定性回归任务与批量采集；探索式长任务仍走 MCP 或 browser-use 类框架。

待核实

  • “比 Playwright MCP 省约 4 倍 token”：社区测评数据（早期版本），官方仅定性表述 more token-efficient，未给倍数。⚠️ 2026-10 更新（#822 引 Checkly 2026-07-30 实测，Claude Code 购物站任务 ×3 次）：任务结束上下文 MCP 约 48-50K vs CLI 约 45-48K——差距已不再数倍。技术原因：新版 Agent 客户端支持按需加载 MCP 工具定义（早期 48 工具定义约 5.9K token 固定开销被消除），且 MCP 也支持快照落盘按需读取（CLI 的文件优势被部分吸收）。两说并存，结论随版本漂移——选型前先测当前版本；注意”任务结束上下文规模”≠“API 计费 token”，样本仅 3 次只作方向参考。
  • dev-browser 对比数据（同任务 3m53s/0.88 vs Playwright Skill 8m07s/1.45）：单篇文章来源，未复现。
  • @playwright/cli 处于 0.1.x 早期，命令面与参数可能变动；本页命令面以 2026-09-19 --help 实测为准。

增补：编年史与竞争格局（2026-09-20 深度研究报告）

  • CLI 的两次生命：2020 年春 playwright-cli 实验包（为人类测试工程师的便利工具，后并入主包）→ 2026 年初 @playwright/cli 独立发布（为 AI 编程代理的省 token 通道）。同一 driver 架构隔着六年伺候两拨用户；
  • MCP→CLI+Skills 的螺旋回归：MCP（2024.12，26 工具 schema 常驻上下文）是为”对话里的模型”设计的，对高频操作的 coding agent 是油老虎；CLI+Skills（2026 初）按需取景，第三方实测 token 最多降至 MCP 的 1/6（NashTech）；官方分工——编程代理用 CLI+Skills，专门 agentic 循环用 MCP；v1.62（2026.7）起两者捆绑进主包 npx playwright mcp / npx playwright cli，分发成本归零；
  • 版本里程碑：v1.56（2025.9）Test Agents（planner/generator/healer）→ v1.59（2026.4）Screencast API + browser.bind() 会话互通 → v1.63（2026.9）trace 内嵌 aria 快照；WebMCP 实验：网页自己向 agent 注册工具（官方警告工具定义来自页面属不可信输入）；
  • 第五类用户论（换代规律）：每代霸主赢在服务新用户（Selenium→测试人员、Puppeteer→前端、Cypress→DX、Playwright→全栈工具链），都死于把上一类用户需求当全部需求；AI 编程代理是第五类用户（要省 token/可组合/无状态），Playwright 用 aria snapshot→Copy prompt→Test Agents→MCP→CLI+skills 连续落子完成卡位——连续两次赢下新用户卡位在工具史是小概率事件，解释变量：从第一天起就在为”非人类操作者”优化接口（先是无头 CI 进程，后是 agent）；
  • 商业化悖论：Cypress 收费墙催生影子生态（Sorry Cypress/Currents）；微软自家 Playwright Testing 两年半即退役（2026.3 关停并入 Azure App Testing）——测试框架本体收费此路不通，微软模式是把 Playwright 当生态沉降槽（免费开源换 Azure/GitHub/VS Code 整体引力）；代价是团队优先级由微软 agent 战略定义，测试工程师应意识到这个工具的”第一用户”正在被重新定义；
  • 风险三处：反爬对抗把 Playwright 指纹当首要识别对象（patchright 分支繁荣是前兆，官方永不下场做 stealth）；Chrome 引擎一家独大后 CDP/BiDi 若封闭化，自建构建维护成本上升；agent 浏览器层安全监管（CVE-2025-9611 DNS rebinding 只是第一声）。

原始素材

  • microsoft/playwright-cli README（官方定位、命令全集、会话模型）
  • 官方 SKILL.md（skill 内容与示例）
  • Playwright CLI + Claude Code 协同实操指南（CLI 执行 + AI 生成脚本的早期两段式用法）
  • 基于 playwright-cli + Skills 实现 UI 自动化测试实战案例（Raina：无障碍树原理、skill 工作流封装、验证码与自愈）
  • Playwright 测试Skills 最佳实践（8 条黄金法则与落地配置）

增补：会话级 token 口径与三条路径（#818，2026-10-25）

  • 官方基准：标准多步骤 UI 会话可超 8 万 token（完整可访问性树 + 二十多个工具 Schema 全量灌入时）——与工具定义级口径（5.9K/13.6K）不同，长流程会顶满上下文，后面的断言/截图/失败定位全被挤掉；
  • 分层解法：MCP 解决『Agent 能不能稳定操控浏览器』，CLI 把状态落盘，Skill 把操作手册固化——三层叠满才算拉满；
  • 三条 UI 路径别混用：localhost 快速预览用内置浏览器就够；已登录公网页做演示交互用本机 Chrome 顺手；要可重复断言、进 MCP 工具链、截图留证 → 默认 Playwright MCP。选型错了会又慢又难断言，还误以为是模型不行；
  • 接入配置：Codex MCP 服务填 npx -y @playwright/mcp@latest；『300 倍提效』为作者体感修辞（人肉点击→自然语言驱动回归的落差），非基准数据。

相关页面

出处 · https://github.com/microsoft/playwright-cli 、npm @playwright/cli、raw/articles/bookmarks/（Playwright CLI + Skills 相关剪藏）

关系图谱

反向链接