Playwright CLI

通过命令行控制浏览器执行自动化任务。适合测试、爬虫、页面交互等场景。

安装

# 安装 Playwright CLI
npm install -g @playwright/cli@latest

# 安装 skills（供 AI agent 使用）
playwright-cli install --skills

# 检查版本
playwright-cli --version
# 输出: 0.1.7

核心命令

浏览器控制

页面交互

键盘鼠标

元素定位

支持多种定位方式：

# CSS 选择器
playwright-cli click "#main > button.submit"

# Role 定位器
playwright-cli click "getByRole('button', { name: 'Submit' })"

# Test ID
playwright-cli click "getByTestId('submit-button')"

# 使用快照引用（推荐）
playwright-cli snapshot  # 获取快照，包含元素引用如 e15
playwright-cli click e15  # 点击引用编号

快照

# 获取页面快照（包含元素引用）
playwright-cli snapshot

# 保存到指定文件
playwright-cli snapshot --filename=after-click.yaml

# 快照特定元素
playwright-cli snapshot "#main"

# 限制快照深度
playwright-cli snapshot --depth=4

Tab 页管理

playwright-cli tab-list    # 列出所有标签页
playwright-cli tab-new [url]  # 新建标签页
playwright-cli tab-close <index>  # 关闭标签页
playwright-cli tab-select <index>  # 切换标签页

存储状态

Cookies:

playwright-cli cookie-list [--domain]  # 列出 Cookies
playwright-cli cookie-get <name>       # 获取 Cookie
playwright-cli cookie-set <name> <val> # 设置 Cookie
playwright-cli cookie-delete <name>    # 删除 Cookie
playwright-cli cookie-clear           # 清除所有 Cookie

LocalStorage:

playwright-cli localstorage-list                   # 列出
playwright-cli localstorage-get <key>             # 获取
playwright-cli localstorage-set <k> <v>           # 设置
playwright-cli localstorage-delete <k>            # 删除
playwright-cli localstorage-clear                 # 清除

保存/恢复状态:

playwright-cli state-save [filename]   # 保存状态
playwright-cli state-load <filename>   # 加载状态

网络拦截

playwright-cli route <pattern> [opts]  # 拦截请求
playwright-cli route-list              # 列出拦截规则
playwright-cli unroute [pattern]       # 移除拦截

调试功能

playwright-cli console [min-level]  # 查看控制台消息
playwright-cli network              # 查看网络请求
playwright-cli run-code <code>      # 执行代码片段
playwright-cli run-code --filename=f  # 执行文件中的代码

录制追踪

playwright-cli tracing-start    # 开始录制
playwright-cli tracing-stop     # 停止录制
playwright-cli video-start [filename]  # 开始录像
playwright-cli video-chapter <title>   # 添加章节标记
playwright-cli video-stop      # 停止录像

浏览器选项

# 使用指定浏览器
playwright-cli open --browser=chrome  # chrome/firefox/webkit

# 有头模式（可见浏览器）
playwright-cli open <url> --headed

# 持久化配置文件
playwright-cli open --persistent

# 使用配置文件
playwright-cli open --config=file.json

# 连接已运行的浏览器
playwright-cli attach --extension

会话管理

# 列出所有会话
playwright-cli list

# 关闭所有浏览器
playwright-cli close-all

# 强制结束所有浏览器进程
playwright-cli kill-all

# 打开可视化仪表盘
playwright-cli show

# 操作指定会话
playwright-cli -s=name open https://example.com  # 在命名会话中打开
playwright-cli -s=name close                    # 关闭命名会话
playwright-cli -s=name delete-data               # 删除会话数据

输出模式

# 输出到文件（默认）
playwright-cli --config path/to/config.json open example.com

# 配置文件中设置
{
  "outputMode": "file",  // 或 "stdout"
  "outputDir": "./playwright-output"
}

环境变量

使用示例

基础操作流程

# 1. 打开页面
playwright-cli open https://demo.playwright.dev/todomvc/

# 2. 截图
playwright-cli screenshot

# 3. 填写待办事项
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter

# 4. 勾选完成
playwright-cli snapshot
playwright-cli check e21
playwright-cli check e35

# 5. 再次截图
playwright-cli screenshot

测试网页功能

# 打开测试页面
playwright-cli open https://demo.playwright.dev/todomvc/ --headed

# 获取快照查看元素
playwright-cli snapshot

# 执行操作并截图
playwright-cli click e15
playwright-cli screenshot

多会话管理

# 创建多个会话
playwright-cli open https://site1.com
playwright-cli -s=session2 open https://site2.com --persistent

# 切换会话
playwright-cli -s=session2 goto /page

# 查看所有会话
playwright-cli list

# 关闭所有
playwright-cli close-all

配置示例

创建 .playwright/cli.config.json:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "headless": false
    },
    "contextOptions": {
      "viewport": {
        "width": 1280,
        "height": 720
      }
    }
  },
  "outputDir": "./playwright-output",
  "outputMode": "file",
  "console": {
    "level": "info"
  },
  "timeouts": {
    "action": 5000,
    "navigation": 60000
  }
}

适用场景

• ✅ 网页功能测试
• ✅ 自动填表、数据采集
• ✅ 页面截图、Pdf 生成
• ✅ 网络请求拦截/mock
• ✅ 浏览器会话录制
• ✅ AI Agent 浏览器控制
• ❌ 不适合复杂登录态维护（建议用 MCP）

注意事项

1. 元素引用（如 e15）来自快照，每次页面变化后需要重新获取快照
2. 默认无头模式，使用 --headed 可视化
3. 临时目录存储，浏览器关闭后数据丢失
4. 使用 --persistent 保存配置文件到磁盘