Playwright CLI 编码代理上手指南：用 playwright-cli 为 Coding Agent 提供 Token 高效的浏览器自动化

playwright-cli 是 Playwright 仓库中面向编码代理（Coding Agents，如 Claude Code、GitHub Copilot）设计的命令行浏览器自动化工具，它用极简的子命令替代庞大的工具 Schema，把“页面快照 + 元素引用 + 会话保持”组织成可被 Agent 低开销消费的交互协议。本文以 docs/src/getting-started-cli.md 为核心骨架，结合本仓库 CLI 源码实现 与 自动化测试用例，完整讲解安装、命令全集、会话模型、监控仪表盘与配置方式，帮助你或你的 Agent 在有限上下文窗口内高效完成浏览器验证任务。

背景与定位：为编码代理而生的浏览器自动化 CLI

随着编码代理在大型代码库中承担越来越多的验证工作，传统“把全部工具定义和冗长可访问性树灌入模型上下文”的方式很快会耗尽上下文预算。Playwright 为此提供了两条互补的路径（本仓库文档将二者并列阐述，见 getting-started-cli.md 的 “playwright-cli vs Playwright MCP” 小节）：

• playwright-cli：面向编码代理场景，以简洁命令与可安装的 Skills 为特征，命令式交互避免把大型工具 Schema 和冗长的可访问性树加载进模型上下文，兼顾浏览器自动化、代码库理解与推理对上下文的争夺。
• Playwright MCP：面向需要持久状态与多轮结构化推理的专门化 Agent 循环（如探索式自动化、长时间自治工作流），详见 MCP 入门指南。

值得注意的是，本仓库根目录 package.json 中暴露了同名的本地开发脚本："playwright-cli": "node packages/playwright-core/lib/tools/cli-client/cli.js"。也就是说，官方发布的 @playwright/cli 包对应的正是仓库中位于 packages/playwright-core/src/tools/cli-client/ 的这一整套 CLI 实现，本文所有命令都能在这个模块的源码中找到真实对应。

前置条件

• Node.js 20 或更新版本（发布为 npm 全局 CLI 工具运行所需）。
• 一个编码代理：Claude Code、GitHub Copilot 或同类工具。

安装

全局安装

npm install -g @playwright/cli@latest
playwright-cli --help

作为本地依赖安装

也可以把 @playwright/cli 安装为项目的本地开发依赖，再用 npx 调用：

npm install -D @playwright/cli@latest
npx playwright cli --help

安装完成后可执行 playwright-cli --help 验证；当检测到 CLAUDECODE 或 COPILOT_CLI 环境变量时，CLI 甚至会在帮助输出中额外打印指向本地 SKILL.md 的提示（见 program.ts），帮助 Agent 发现可用的能力描述。

安装 Skills（命令技能包）

Claude Code、GitHub Copilot 这类编码代理可以使用本地安装的 Skills 获得关于可用命令的更丰富上下文：

playwright-cli install --skills

如果希望 Skills 在所有项目中共享，加上 -g 标志可将其安装到用户主目录（~/.claude/skills，若使用 --skills=agents 则安装到 ~/.agents/skills）：

playwright-cli install --skills -g

从源码看，install 命令通过 runInitWorkspace 拉起 cliDaemon.js，携带 --init-workspace 与 --init-skills（或 --init-skills-global）参数完成工作区与 Skills 的初始化；同时校验“-g 只能与 --skills 搭配使用”。仓库内的 Skills 模板位于 packages/playwright-core/src/tools/skills/ 目录（如 playwright-component-testing 等），而 playwright-cli 自身的 SKILL.md 由 program.ts 通过 libPath('tools', 'skills', 'playwright-cli', 'SKILL.md') 解析。

不使用 Skills 的操作方式

也可以不安装 Skills，直接让 Agent 指向 CLI 本身、自行通过 --help 发现命令。例如向 Agent 下达如下指令：

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

快速上手

交互式演示

最直接的体验方式是把任务交给编码代理：

Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.

手动走一遍全流程

也可以逐条手动执行命令，直观感受 CLI 的工作方式：

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 screenshot

每次命令后的页面快照输出

几乎每条交互命令执行后，CLI 都会输出当前页面的状态摘要与快照，这是 Agent 判断下一步动作的核心依据。典型的输出形如：

### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Snapshot
Snapshot

快照会以 YAML 文件形式落到当前目录下的 .playwright-cli/ 文件夹中，里面携带可供后续命令直接引用的元素引用。这一行为在仓库测试中被精确断言：例如 tests/mcp/cli-core.spec.ts 验证 open 后输出包含 ### Page、Page URL、Page Title，且快照内出现 - generic [active] [ref=e1]: Hello, world! 形式的行，其中 [ref=e1] 就是元素引用。

核心命令

页面交互

playwright-cli open [url]               # open browser, optionally navigate to url
playwright-cli goto <url>               # navigate to a url
playwright-cli click <ref> [button]     # click an element
playwright-cli type <text>              # type text into editable element
playwright-cli fill <ref> <text>        # fill text into editable element
playwright-cli select <ref> <value>     # select an option in a dropdown
playwright-cli check <ref>              # check a checkbox or radio button
playwright-cli uncheck <ref>            # uncheck a checkbox
playwright-cli hover <ref>              # hover over element
playwright-cli drag <startRef> <endRef> # drag and drop between elements
playwright-cli upload <files...>        # upload one or multiple files
playwright-cli close                    # close the page

一个很有价值的实现细节：点击等动作执行后，CLI 会输出“### Ran Playwright code”代码块，展示它背后生成的等价 Playwright 代码。如 cli-core.spec.ts 所示，click e2 会生成 await page.getByRole('button', { name: 'Submit' }).click();——这让 Agent 不仅能驱动浏览器，还能反向学到可复用的定位写法。

元素定位

playwright-cli 的核心定位模型是“快照元素引用（ref）驱动”，也支持 CSS 选择器与 Playwright 角色（role）选择器：

playwright-cli snapshot                 # get snapshot with element refs
playwright-cli click e15                # click using a ref

CSS / role 选择器示例：

playwright-cli click "#main > button.submit"
playwright-cli click "role=button[name=Submit]"
playwright-cli click "#footer >> role=button[name=Submit]"

第三种写法演示了 Playwright 特有的 >> 链式组合：先在 #footer 范围内再按角色定位 Submit 按钮。

截图与快照

playwright-cli snapshot                 # capture page snapshot
playwright-cli snapshot --filename=f    # save snapshot to specific file
playwright-cli screenshot               # screenshot of the current page
playwright-cli screenshot [ref]         # screenshot of a specific element
playwright-cli screenshot --filename=f  # save with specific filename
playwright-cli screenshot --hires       # capture using device pixels
playwright-cli pdf                      # save page as PDF

其中 screenshot --hires 表示按设备像素（device pixels）而非 CSS 像素捕获，适合对高 DPI 页面做像素级截图比对。

导航

playwright-cli go-back                  # go back
playwright-cli go-forward               # go forward
playwright-cli reload                   # reload the page

键盘与鼠标

playwright-cli press <key>              # press a key (e.g. Enter, ArrowLeft)
playwright-cli keydown <key>            # key down
playwright-cli keyup <key>              # key up
playwright-cli mousemove <x> <y>        # move mouse
playwright-cli mousedown [button]       # mouse button down
playwright-cli mouseup [button]         # mouse button up
playwright-cli mousewheel <dx> <dy>     # scroll

标签页

playwright-cli tab-list                 # list all tabs
playwright-cli tab-new [url]            # create a new tab
playwright-cli tab-select <index>       # select a tab
playwright-cli tab-close [index]        # close a tab

网络

playwright-cli requests                 # list network requests since page load
playwright-cli request <num>            # show full details of a single request
playwright-cli route <pattern> [opts]   # mock network requests
playwright-cli route-list               # list active routes
playwright-cli unroute [pattern]        # remove routes

route 系列让你可以在不写代码的情况下对页面请求进行 Mock 与拦截，仓库在 tests/mcp/cli-route.spec.ts 中对其有完整的端到端覆盖。

存储状态

playwright-cli state-save [filename]    # save storage state (cookies, localStorage)
playwright-cli state-load <filename>    # load storage state

# Cookies
playwright-cli cookie-list [--domain]   # list cookies
playwright-cli cookie-get <name>        # get a cookie
playwright-cli cookie-set <name> <val>  # set a cookie
playwright-cli cookie-delete <name>     # delete a cookie
playwright-cli cookie-clear             # clear all cookies

# localStorage
playwright-cli localstorage-list        # list entries
playwright-cli localstorage-get <key>   # get value
playwright-cli localstorage-set <k> <v> # set value
playwright-cli localstorage-delete <k>  # delete entry
playwright-cli localstorage-clear       # clear all

登录态持久化是 Agent 自动化中高频需求：state-save 把 Cookie 与 localStorage 落地成文件，配合会话持久化可在下次运行中无缝续接登录状态。

DevTools 与调试

playwright-cli console [min-level]      # list console messages
playwright-cli eval <func> [ref]        # evaluate JavaScript on page
playwright-cli run-code <code>          # run Playwright code snippet
playwright-cli tracing-start            # start trace recording
playwright-cli tracing-stop             # stop trace recording
playwright-cli video-start              # start video recording
playwright-cli video-chapter <title>    # add chapter marker to video
playwright-cli video-stop --filename=f  # stop video recording

• console 可按最低级别过滤查看浏览器控制台消息，是捕获页面报错的第一抓手。
• run-code 支持直接在页面上下文里执行一段 Playwright 代码片段（相关测试见 tests/mcp/cli-run-code.spec.ts），可作为“命令表达不了时再退回代码”的逃生舱。
• video-chapter 可在录制中为视频插入章节标记，方便把长流程切成可定位的段落。

会话模型

CLI 默认把浏览器配置（profile）保存在内存中——同一会话内多次调用之间 Cookie 与存储状态得以保留，但浏览器关闭即丢失。若需持久化到磁盘，使用 --persistent。

底层架构上，每次交互并非直接启动一个一次性浏览器，而是由 program.ts 通过 Session / Registry 管理一组常驻的后台守护进程：open/attach 走 startSession（会先停掉同名旧会话再 Session.startDaemon），其余普通命令则通过 runInSession 把参数转发给对应会话执行（program.ts）。这也是命令之间能“接力”操作同一浏览器的原因。

命名会话（Named Sessions）

可以为不同项目同时运行多个互不干扰的浏览器实例：

playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list                     # list all sessions

第一条命令使用默认会话（名为 default），第二条通过 -s=example（等价于 --session=example）显式创建并持久化一个命名会话。源码中 -s 与 -g 别名分别被规范化为 --session 与 --global（program.ts）。

还可以把某个会话固定给编码代理使用——用环境变量告知代理“浏览器已就绪”：

PLAYWRIGHT_CLI_SESSION=todo-app claude .

之后在该环境下启动的 Claude Code 就会自动接入名为 todo-app 的浏览器会话。

会话管理

playwright-cli list                     # list all sessions
playwright-cli close-all                # close all browsers
playwright-cli kill-all                 # forcefully kill all browser processes
playwright-cli -s=name delete-data      # delete user data for a named session

• close-all 优雅关闭当前客户端相关的全部会话（对应源码中遍历 registry.entries(clientInfo) 逐个 Session.stop）；
• kill-all 则按进程名模式（如 cli-daemon、cliDaemon.js、dashboardApp.js 等）强制清杀后台守护进程，跨平台分别使用 PowerShell 与 ps auxww 实现（program.ts），适合“浏览器卡死但守护进程还活着”的清理场景；
• delete-data 用于清除某个命名会话的用户数据目录，等价于“重置该会话的登录态与存储”。

list 会给出每个会话的名称、所属工作区、状态（open/closed）、浏览器类型、userDataDir、是否 headed、是否 persistent、是否 attach 及版本兼容性等结构化信息，并支持 --all 跨工作区列举（program.ts）。

监控：playwright-cli show 可视化仪表盘

playwright-cli show 会打开一个可视化仪表盘，用于观察并远程控制所有正在运行的浏览器会话：

playwright-cli show

仪表盘提供两类核心视图：

• 会话网格（Session grid）：按工作区分组展示所有活动会话，每个会话带实时投屏预览（screencast）、会话名称、当前 URL 与页面标题；点击任一会话即可放大查看。
• 会话详情（Session detail）：选中会话的实时视图，提供标签栏、导航控制与完整远程控制能力；点击视口可接管鼠标键盘操作，按 Escape 释放控制权。

从实现看，show 会启动 dashboardApp.js 守护进程（可指定 --sessionName 精确定位会话，也支持 --port、--host、--kill 等参数），并等待 “Dashboard is running” 就绪信号后返回（program.ts）。仓库中 tests/mcp/dashboard.spec.ts 与 cli-fixtures.ts 中的 startDashboardServer fixture 完整覆盖了“启动仪表盘 → 页面 goto → 交互”的链路。当 Agent 需要人工介入排查复杂问题时，这个仪表盘就是最直观的“遥控器”。

配置

有头模式（Headed mode）

CLI 默认无头（headless）运行；需要肉眼观察浏览器时加上 --headed：

playwright-cli open https://playwright.dev --headed

浏览器选择

playwright-cli open --browser=chrome    # use specific browser
playwright-cli open --browser=firefox
playwright-cli open --browser=webkit
playwright-cli open --browser=msedge

其中 chrome/msedge 对应本仓库浏览器支持矩阵中的 Chromium 频道分支（Chromium 版本基于 Google Chrome 对应里程碑构建），而 Firefox 与 WebKit 则是 Playwright 自行维护的构建版本。除浏览器外，open 命令还支持 --device、--mobile、--profile 等选项（见 program.ts 的 OpenOptions 定义）。

配置文件

更进阶的设置可以放在 JSON 配置文件中：

playwright-cli --config path/to/config.json open example.com

CLI 也会自动加载当前目录下存在的 .playwright/cli.config.json。配置文件支持浏览器选项（browser options）、上下文选项（context options）、网络规则（network rules）、超时（timeouts）等；完整的可用选项清单以 playwright-cli --help 输出为准。仓库测试 tests/mcp/cli-config.spec.ts 与 config-resolve.spec.ts 覆盖了配置文件解析与加载优先级相关的行为。

浏览器扩展：接管现有标签页

如果不想每次都新起浏览器，而是复用你自己正在使用的浏览器标签页，可以用 attach 模式：

playwright-cli attach --extension

这需要预先安装 Playwright 浏览器扩展，其源码与使用说明见本仓库 packages/extension/README.md。从 program.ts 看，attach 支持三类连接目标且互斥校验：直接目标名/--endpoint、--cdp 频道、--extension 扩展；成功连接后会话会进入 attached 状态，并可执行 snapshot 获取初始快照、用 detach 优雅脱离（对 attached 会话才允许 detach）。

命令速查表

操作	命令
安装 CLI	npm install -g @playwright/cli@latest
安装 Skills	playwright-cli install --skills
打开页面	playwright-cli open https://example.com
点击元素	playwright-cli click e15
输入文本	playwright-cli type "hello world"
页面截图	playwright-cli screenshot
获取页面快照	playwright-cli snapshot
有头运行	playwright-cli open https://example.com --headed
使用 Firefox	playwright-cli open --browser=firefox
监控会话	playwright-cli show

深入阅读

• 多数命令支持 --json 结构化输出（对应 program.ts 中 JsonOutput/TextOutput 的输出分发），便于 Agent 以 JSON 而非文本解析结果；仓库的 tests/mcp/cli-json.spec.ts 提供了相关断言样例。
• 需要以编程方式完整验证 CLI 行为时，可直接研读测试夹具 tests/mcp/cli-fixtures.ts（封装了 cli(...) 运行器、会话清理与仪表盘辅助函数）以及 tests/mcp/cli-core.spec.ts 等一整套端到端用例。
• 从 CLI 交互进一步走向常规测试编写，可阅读 Writing Tests（JS 版）指南，了解 web-first 断言、fixture 与 locator 的完整用法。
• 想要把自动化搬到持续集成环境，参见 CI 入门。
• 需要诊断回放与时间线分析时，可借助 Trace Viewer 深入排查，见 Trace Viewer 指南。