企业官网建设流程全解析

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

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright

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 中的startDashboardServerfixture 完整覆盖了“启动仪表盘 → 页面 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）。

命令速查表

深入阅读

• 多数命令支持--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 指南。

【免费下载链接】playwrightPlaywright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.项目地址: https://gitcode.com/GitHub_Trending/pl/playwright