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/playwrightplaywright-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/clilatest playwright-cli --help作为本地依赖安装也可以把playwright/cli安装为项目的本地开发依赖再用npx调用npm install -D playwright/clilatest 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若使用--skillsagents则安装到~/.agents/skillsplaywright-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] [refe1]: Hello, world!形式的行其中[refe1]就是元素引用。核心命令页面交互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 refCSS / role 选择器示例playwright-cli click #main button.submit playwright-cli click rolebutton[nameSubmit] playwright-cli click #footer rolebutton[nameSubmit]第三种写法演示了 Playwright 特有的链式组合先在#footer范围内再按角色定位Submit按钮。截图与快照playwright-cli snapshot # capture page snapshot playwright-cli snapshot --filenamef # 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 --filenamef # 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 routesroute系列让你可以在不写代码的情况下对页面请求进行 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 --filenamef # stop video recordingconsole可按最低级别过滤查看浏览器控制台消息是捕获页面报错的第一抓手。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 -sexample open https://example.com --persistent playwright-cli list # list all sessions第一条命令使用默认会话名为default第二条通过-sexample等价于--sessionexample显式创建并持久化一个命名会话。源码中-s与-g别名分别被规范化为--session与--globalprogram.ts。还可以把某个会话固定给编码代理使用——用环境变量告知代理“浏览器已就绪”PLAYWRIGHT_CLI_SESSIONtodo-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 -sname delete-data # delete user data for a named sessionclose-all优雅关闭当前客户端相关的全部会话对应源码中遍历registry.entries(clientInfo)逐个Session.stopkill-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 modeCLI 默认无头headless运行需要肉眼观察浏览器时加上--headedplaywright-cli open https://playwright.dev --headed浏览器选择playwright-cli open --browserchrome # use specific browser playwright-cli open --browserfirefox playwright-cli open --browserwebkit playwright-cli open --browsermsedge其中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.comCLI 也会自动加载当前目录下存在的.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。命令速查表操作命令安装 CLInpm install -g playwright/clilatest安装 Skillsplaywright-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使用 Firefoxplaywright-cli open --browserfirefox监控会话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 TestsJS 版指南了解 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考