Playwright CLI

Playwright CLI（@playwright/cli）是 Playwright 官方提供的命令行浏览器自动化工具，让你无需编写代码，即可通过命令行操控浏览器完成页面导航、元素交互、截图、网络拦截、状态管理等操作，非常适合快速原型验证、自动化测试、数据抓取和 CI/CD 集成。

Playwright CLI 与 Playwright 的关系

Playwright：Node.js 库，提供完整的浏览器自动化 API，需要通过编写代码来使用
Playwright CLI：Playwright 的命令行封装，将常用 API 暴露为命令行指令，适合快速调试、脚本化和流水线集成

两者共享同一套浏览器驱动，底层能力完全一致。

安装与环境配置

安装 CLI

bash

npm install -g @playwright/cli@latest

安装浏览器

首次使用前需要安装浏览器二进制文件：

bash

playwright-cli install-browser

默认安装 Chromium。如需指定浏览器，可在打开时通过 --browser 参数选择：

bash

playwright-cli open --browser=chrome    # Chrome
playwright-cli open --browser=firefox   # Firefox
playwright-cli open --browser=webkit    # WebKit (Safari 内核)
playwright-cli open --browser=msedge    # Microsoft Edge

核心工作流

Playwright CLI 的核心工作流是：打开 → 快照 → 操作 → 验证 → 关闭。

最简示例

bash

# 1. 打开浏览器并导航
playwright-cli open https://playwright.dev

# 2. 拍摄快照，获取页面元素的引用 ID（ref）
playwright-cli snapshot

# 3. 读取快照文件，找到目标元素的 ref 编号
# Windows: type .playwright-cli\page-*.yml
# Linux/macOS: cat .playwright-cli/page-*.yml

# 4. 通过 ref 编号操作页面元素
playwright-cli click e15          # 点击 ref 为 e15 的元素
playwright-cli type "搜索内容"     # 在焦点元素中输入

# 5. 截图确认结果
playwright-cli screenshot

# 6. 关闭浏览器
playwright-cli close

快照输出说明

snapshot 命令默认将页面元素引用保存到 .playwright-cli/ 目录下的 YAML 文件中，而非直接输出到命令行。你可以通过 cat（Linux/macOS）或 type（Windows）读取文件内容。

如需直接输出到标准输出，可在 playwright-cli.json 配置文件中设置 { "outputMode": "stdout" }。

命令参考

页面导航

命令	说明
`goto <url>`	导航到指定 URL
`go-back`	后退到上一页
`go-forward`	前进到下一页
`reload`	刷新当前页面

元素交互

命令	说明	示例
`click <ref>`	单击元素	`click e5`
`dblclick <ref>`	双击元素	`dblclick e7`
`fill <ref> <text>`	填充输入框（先清空再输入）	`fill e3 "hello@example.com"`
`type <text>`	逐字输入到焦点元素	`type "搜索内容"`
`hover <ref>`	鼠标悬停	`hover e4`
`drag <from> <to>`	拖拽元素	`drag e2 e8`
`select <ref> <value>`	选择下拉选项	`select e9 "选项值"`
`check <ref>`	勾选复选框	`check e12`
`uncheck <ref>`	取消勾选	`uncheck e12`
`upload <file>`	上传文件	`upload ./document.pdf`

键盘与鼠标

命令	说明
`press <key>`	按下按键（Enter、ArrowDown、Tab 等）
`keydown <key>`	按住按键不放
`keyup <key>`	释放按键
`mousemove <x> <y>`	移动鼠标到坐标
`mousedown [right]`	按下鼠标（可选右键）
`mouseup [right]`	释放鼠标（可选右键）
`mousewheel <dx> <dy>`	滚动鼠标滚轮

截图与导出

命令	说明
`screenshot`	截取整个页面
`screenshot <ref>`	截取指定元素
`screenshot --filename=page.png`	指定文件名
`pdf --filename=page.pdf`	导出为 PDF

弹窗处理

命令	说明
`dialog-accept [text]`	接受弹窗（可选填入文本）
`dialog-dismiss`	取消弹窗

执行 JavaScript

命令	说明	示例
`eval <expression>`	在页面中执行 JS 表达式	`eval "document.title"`
`eval <expression> <ref>`	对指定元素执行 JS	`eval "el => el.textContent" e5`
`run-code <code>`	执行 Playwright 代码	参考下文「高级用法」

多标签页管理

bash

playwright-cli tab-list                # 列出所有标签页
playwright-cli tab-new                  # 打开新标签页（空白）
playwright-cli tab-new https://example.com  # 打开指定 URL
playwright-cli tab-select 0            # 切换到第 0 个标签页
playwright-cli tab-close               # 关闭当前标签页
playwright-cli tab-close 2             # 关闭第 2 个标签页

存储状态管理

Playwright CLI 支持管理浏览器的 Cookies、LocalStorage 和 SessionStorage，方便进行登录态维护和数据验证。

Cookies

bash

playwright-cli cookie-list                        # 列出所有 Cookie
playwright-cli cookie-list --domain=example.com   # 按域名筛选
playwright-cli cookie-get session_id              # 获取指定 Cookie
playwright-cli cookie-set session_id abc123       # 设置 Cookie
playwright-cli cookie-set token xyz --domain=example.com --httpOnly --secure
playwright-cli cookie-delete session_id           # 删除 Cookie
playwright-cli cookie-clear                       # 清除所有 Cookie

LocalStorage / SessionStorage

bash

# LocalStorage
playwright-cli localstorage-list          # 列出
playwright-cli localstorage-get theme     # 读取
playwright-cli localstorage-set theme dark  # 设置
playwright-cli localstorage-delete theme  # 删除
playwright-cli localstorage-clear         # 清空

# SessionStorage（命令格式与 LocalStorage 一致）
playwright-cli sessionstorage-list
playwright-cli sessionstorage-get step
playwright-cli sessionstorage-set step 3
playwright-cli sessionstorage-delete step
playwright-cli sessionstorage-clear

状态保存与恢复

bash

# 保存当前浏览器状态（Cookie、LocalStorage 等）
playwright-cli state-save
playwright-cli state-save auth.json

# 恢复浏览器状态
playwright-cli state-load auth.json

网络拦截与 Mock

路由（Route）功能可以拦截特定请求，返回模拟数据或修改响应，非常适合前后端并行开发或测试异常场景。

bash

# 拦截所有图片请求，返回 404
playwright-cli route "**/*.jpg" --status=404

# Mock API 响应
playwright-cli route "https://api.example.com/**" --body='{"mock": true}'

# 查看当前路由规则
playwright-cli route-list

# 取消指定路由
playwright-cli unroute "**/*.jpg"

# 取消所有路由
playwright-cli unroute

DevTools 调试

Playwright CLI 内置了 DevTools 调试能力，方便排查问题。

控制台与网络

bash

# 查看控制台日志
playwright-cli console
playwright-cli console warning     # 仅查看警告级别

# 查看网络请求
playwright-cli network

Tracing（性能追踪）

bash

playwright-cli tracing-start       # 开始录制
# ... 执行操作 ...
playwright-cli tracing-stop        # 停止录制，生成 trace 文件

生成的文件可用 playwright show-trace <trace-file> 或在 trace.playwright.dev 中查看。

视频录制

bash

playwright-cli video-start         # 开始录制
# ... 执行操作 ...
playwright-cli video-stop video.webm  # 停止并保存

浏览器会话管理

多会话

通过 -s 参数可以创建独立命名的浏览器会话：

bash

# 创建命名会话
playwright-cli -s=mysession open https://example.com --persistent

# 在指定会话中操作
playwright-cli -s=mysession click e6

# 关闭指定会话
playwright-cli -s=mysession close

# 列出所有活跃会话
playwright-cli list

# 关闭所有会话
playwright-cli close-all

# 强制终止所有浏览器进程
playwright-cli kill-all

持久化 Profile

默认情况下，每次打开的浏览器会话是临时的（内存模式）。使用 --persistent 可让 Cookie、LocalStorage 等在会话间保持：

bash

# 使用默认持久化目录
playwright-cli open --persistent

# 使用自定义持久化目录
playwright-cli open --profile=/path/to/profile

# 删除会话数据
playwright-cli delete-data
playwright-cli -s=mysession delete-data

连接已有浏览器

通过 --extension 参数，可以连接到已有浏览器的 Playwright 扩展，复用登录态等：

bash

playwright-cli open --extension

页面尺寸调整

bash

# 重置视口尺寸
playwright-cli resize 1920 1080

典型实践案例

案例一：表单自动提交

bash

# 打开表单页面
playwright-cli open https://example.com/login
playwright-cli snapshot --filename=login.yaml

# 读取快照，找到用户名、密码输入框和登录按钮的 ref
# type .playwright-cli\login.yaml

# 填写表单
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3

# 验证结果
playwright-cli snapshot --filename=result.yaml
playwright-cli screenshot --filename=after-login.png

playwright-cli close

案例二：多标签页工作流

bash

playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0                # 切回第一个标签页
playwright-cli snapshot
playwright-cli close

案例三：登录态持久化

借助持久化 Profile，登录一次即可在多次操作中复用登录态：

bash

# 首次：登录并保存状态
playwright-cli open https://app.example.com --persistent
playwright-cli snapshot
# ... 完成登录操作 ...
playwright-cli state-save login-state.json
playwright-cli close

# 后续：加载登录态，直接进入已登录页面
playwright-cli open https://app.example.com/dashboard --persistent
playwright-cli state-load login-state.json
playwright-cli snapshot
playwright-cli close

案例四：API Mock 测试异常场景

bash

playwright-cli open https://app.example.com

# Mock：让 API 返回 500 错误
playwright-cli route "https://api.example.com/users/**" --status=500 --body='{"error":"Internal Server Error"}'

# 操作页面，验证错误处理 UI
playwright-cli click e5
playwright-cli screenshot --filename=error-state.png

playwright-cli close

CI/CD 集成

Playwright CLI 非常适合在 CI/CD 流水线中执行轻量级的浏览器自动化任务。

GitHub Actions 示例

yaml

name: E2E Smoke Test

on:
  push:
    branches: [main]

jobs:
  smoke-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Playwright CLI
        run: npm install -g @playwright/cli@latest

      - name: Install Browsers
        run: playwright-cli install-browser

      - name: Run Smoke Test
        run: |
          playwright-cli open https://your-app.com
          playwright-cli snapshot
          playwright-cli screenshot --filename=homepage.png
          playwright-cli close

      - name: Upload Screenshot
        uses: actions/upload-artifact@v4
        with:
          name: smoke-test-screenshots
          path: homepage.png

无头模式

CI 环境中浏览器默认以 headless 模式运行，无需额外配置。如需调试，可在配置中关闭：

json

// playwright-cli.json
{
  "headless": false
}

高级用法

执行 Playwright 代码

对于 CLI 无法覆盖的复杂场景，可以用 run-code 直接执行 Playwright 代码：

bash

playwright-cli run-code "async page => {
  await page.context().grantPermissions(['geolocation']);
  await page.setGeolocation({ latitude: 39.9042, longitude: 116.4074 });
}"

配置文件中管理命令

可以创建 playwright-cli.json 配置文件，统一管理常用参数：

json

{
  "outputMode": "stdout",
  "browser": "chrome",
  "headless": false,
  "viewport": { "width": 1920, "height": 1080 }
}

使用配置文件启动：

bash

playwright-cli open --config=playwright-cli.json

与其他工具对比

特性	Playwright CLI	Puppeteer	Selenium IDE
多浏览器支持	Chrome/Firefox/WebKit/Edge	Chrome/Firefox	Chrome/Firefox/Edge
安装方式	npm 全局安装	npm 项目依赖	浏览器插件
编程接口	CLI + Node.js API	Node.js API	录制回放
网络拦截	原生支持	原生支持	有限
多标签页	原生支持	支持	支持
CI/CD 友好	高	高	中
学习曲线	低	中	低

总结

Playwright CLI 是一个轻量级但有强大能力的命令行浏览器自动化工具，特别适合以下场景：

快速验证：无需编写代码，命令行即可完成页面操作和截图
自动化测试：在 CI/CD 流水线中执行冒烟测试、页面可用性检查
数据抓取：配合 snapshot 和 eval 提取页面数据
前后端联调：通过 route 命令 Mock API，前端独立开发调试

它填补了「写代码太重、纯手工太慢」之间的空白，是开发者工具箱中的实用利器。

作者：yanshaodong

Playwright CLI ​

Playwright CLI 与 Playwright 的关系 ​

安装与环境配置 ​

安装 CLI ​

安装浏览器 ​

核心工作流 ​

最简示例 ​

命令参考 ​

页面导航 ​

元素交互 ​

键盘与鼠标 ​

截图与导出 ​

弹窗处理 ​

执行 JavaScript ​

多标签页管理 ​

存储状态管理 ​

Cookies ​

LocalStorage / SessionStorage ​

状态保存与恢复 ​

网络拦截与 Mock ​

DevTools 调试 ​

控制台与网络 ​

Tracing（性能追踪） ​

视频录制 ​

浏览器会话管理 ​

多会话 ​

持久化 Profile ​

连接已有浏览器 ​

页面尺寸调整 ​

典型实践案例 ​

案例一：表单自动提交 ​

案例二：多标签页工作流 ​

案例三：登录态持久化 ​

案例四：API Mock 测试异常场景 ​

CI/CD 集成 ​

GitHub Actions 示例 ​

无头模式 ​

高级用法 ​

执行 Playwright 代码 ​

配置文件中管理命令 ​

与其他工具对比 ​

总结 ​

Playwright CLI

Playwright CLI 与 Playwright 的关系

安装与环境配置

安装 CLI

安装浏览器

核心工作流

最简示例

命令参考

页面导航

元素交互

键盘与鼠标

截图与导出

弹窗处理

执行 JavaScript

多标签页管理

存储状态管理

Cookies

LocalStorage / SessionStorage

状态保存与恢复

网络拦截与 Mock

DevTools 调试

控制台与网络

Tracing（性能追踪）

视频录制

浏览器会话管理

多会话

持久化 Profile

连接已有浏览器

页面尺寸调整

典型实践案例

案例一：表单自动提交

案例二：多标签页工作流

案例三：登录态持久化

案例四：API Mock 测试异常场景

CI/CD 集成

GitHub Actions 示例

无头模式

高级用法

执行 Playwright 代码

配置文件中管理命令

与其他工具对比

总结