编码助手 (Coding agents)

简介

Playwright 附带了 playwright-cli，这是一个专为编码智能体设计的浏览器自动化命令行界面。它通过简洁的 CLI 命令和可安装的技能提供令牌（Token）高效的浏览器控制，非常适合那些需要在有限上下文窗口内兼顾浏览器自动化、大型代码库处理和推理任务的智能体。

`playwright-cli` 与 Playwright MCP 的对比

playwright-cli 最适合 编码智能体（如 Claude Code, GitHub Copilot 等），这些智能体偏好令牌高效、基于技能的工作流。CLI 命令避免了将庞大的工具架构和冗长的辅助功能树加载到模型上下文中。
MCP 最适合那些得益于持久状态和针对页面结构进行迭代推理的专用智能体循环，例如探索性自动化或长时间运行的自主工作流。请参阅 MCP 入门指南。

先决条件

在开始之前，请确保已安装以下内容

Node.js 18 或更高版本
一个编码智能体：Claude Code、GitHub Copilot 或类似工具

安装

全局安装 playwright-cli

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

或者，将 @playwright/cli 作为本地依赖项安装并使用 npx

npx playwright-cli --help

安装技能

像 Claude Code 和 GitHub Copilot 这样的编码智能体可以使用本地安装的技能，以获取有关可用命令的更丰富上下文

playwright-cli install --skills

无技能模式操作

你也可以让智能体直接指向 CLI，并让它自行发现命令

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 都会输出当前页面状态的快照

### Page
- Page URL: https://demo.playwright.dev/todomvc/#/
- Page Title: React • TodoMVC
### Snapshot
[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)

核心命令

与页面交互

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 <file>            # upload files
playwright-cli close                    # close the page

定位元素

使用快照中的元素引用（ref）来定位元素

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-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 pdf                      # save page as PDF

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 network                  # list network requests since page load
playwright-cli route <pattern> [opts]   # mock network requests
playwright-cli route-list               # list active routes
playwright-cli unroute [pattern]        # remove routes

存储

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

开发者工具（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

会话

CLI 默认将浏览器配置文件保留在内存中 — Cookie 和存储状态在会话内的调用之间保持，但在浏览器关闭时丢失。使用 --persistent 将配置文件保存到磁盘。

命名会话

为不同项目运行多个浏览器实例

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

你可以配置你的编码智能体以使用特定的会话

PLAYWRIGHT_CLI_SESSION=todo-app claude .

会话管理

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

监控

使用 playwright-cli show 打开可视化仪表板，用于观察和控制所有正在运行的浏览器会话

playwright-cli show

仪表板提供

会话网格 — 所有按工作区分组的活动会话，每个会话都有实时截屏预览、会话名称、当前 URL 和页面标题。点击任何会话即可放大。
会话详情 — 所选会话的实时视图，带有标签栏、导航控件和完全远程控制功能。点击视口即可接管鼠标和键盘；按 Escape 键释放。

配置

有头模式

CLI 默认以无头模式（headless）运行。要查看浏览器

playwright-cli open https://playwright.net.cn --headed

浏览器选择

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

配置文件

对于高级设置，请使用 JSON 配置文件

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

如果存在，CLI 还会自动加载 .playwright/cli.config.json。配置文件支持浏览器选项、上下文选项、网络规则、超时等。运行 playwright-cli --help 获取完整选项列表。

浏览器扩展

连接到你现有的浏览器标签页，而不是启动一个新的浏览器

playwright-cli open --extension

这需要安装 Playwright MCP Bridge 浏览器扩展。

快速参考

操作	命令
安装 CLI	`npm install -g @playwright/cli@latest`
安装技能	`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`

简介​

playwright-cli 与 Playwright MCP 的对比​

先决条件​

安装​

安装技能​

无技能模式操作​

第一步​

交互式演示​

手动演练​

核心命令​

与页面交互​

定位元素​

截图和快照​

导航​

键盘和鼠标​

标签页​

网络​

存储​

开发者工具（DevTools）​

会话​

命名会话​

会话管理​

监控​

配置​

有头模式​

浏览器选择​

配置文件​

浏览器扩展​

快速参考​

接下来​

简介