Playwright CLI#

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

安装#

bash

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

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

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

核心命令#

浏览器控制#

命令说明playwright-cli open <url>打开浏览器访问 URLplaywright-cli goto <url>导航到指定 URLplaywright-cli close关闭当前页面playwright-cli screenshot [ref]截图（当前页面或指定元素）playwright-cli screenshot --filename=f保存截图到指定文件playwright-cli pdf保存页面为 PDFplaywright-cli pdf --filename=page.pdf保存 PDF 到指定文件playwright-cli resize <w> <h>调整浏览器窗口大小playwright-cli reload刷新当前页面playwright-cli go-back后退playwright-cli go-forward前进

页面交互#

命令说明playwright-cli click <ref>点击元素playwright-cli dblclick <ref>双击元素playwright-cli fill <ref> <text>填写表单playwright-cli fill <ref> <text> --submit填写并回车playwright-cli type <text>输入文本playwright-cli hover <ref>鼠标悬停playwright-cli drag <startRef> <endRef>拖拽操作playwright-cli select <ref> <val>选择下拉选项playwright-cli check <ref>勾选复选框/单选框playwright-cli uncheck <ref>取消勾选playwright-cli upload <file>上传文件playwright-cli press <key>按键（如 Enter、ArrowLeft）

键盘鼠标#

命令说明playwright-cli keydown <key>按下键盘按键playwright-cli keyup <key>释放键盘按键playwright-cli mousemove <x> <y>移动鼠标playwright-cli mousedown [button]鼠标按下playwright-cli mouseup [button]鼠标释放playwright-cli mousewheel <dx> <dy>滚动鼠标

元素定位#

支持多种定位方式：

bash

# 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  # 点击引用编号

快照#

bash

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

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

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

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

Tab 页管理#

bash

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

存储状态#

Cookies:

bash

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:

bash

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

保存/恢复状态:

bash

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

网络拦截#

bash

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

调试功能#

bash

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

录制追踪#

bash

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

浏览器选项#

bash

# 使用指定浏览器
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

会话管理#

bash

# 列出所有会话
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               # 删除会话数据

输出模式#

bash

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

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

环境变量#

变量说明默认值PLAYWRIGHT_MCP_BROWSER浏览器类型chromePLAYWRIGHT_MCP_HEADLESS是否无头truePLAYWRIGHT_MCP_CONSOLE_LEVEL控制台级别infoPLAYWRIGHT_MCP_TIMEOUT_ACTION操作超时(毫秒)5000PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION导航超时(毫秒)60000PLAYWRIGHT_MCP_VIEWPORT_SIZE窗口大小1280x720PLAYWRIGHT_MCP_OUTPUT_DIR输出目录./outputPLAYWRIGHT_MCP_SAVE_VIDEO保存视频-PLAYWRIGHT_MCP_SAVE_TRACE保存追踪-

使用示例#

基础操作流程#

bash

# 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

测试网页功能#

bash

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

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

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

多会话管理#

bash

# 创建多个会话
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:

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 保存配置文件到磁盘