首页 @playwright/cli / playwright-cli
0.1.13 2026-05-07 microsoft/playwright-cli
打开 Zread CodeWiki
340px

快速定位

  • 适合场景：让 agent 驱动真实浏览器、做页面交互、抓取状态、录屏、录 trace、管理会话
  • open snapshot click/fill screenshot pdf state-save：安装 CLI -> 页面 -> 拿 ref -> 操作 -> / /
  • playwright-cli
  • 0.1.13
  • 2026-05-07
  • microsoft/playwright-cli
# 全局安装
npm install -g @playwright/cli@latest

# 看帮助
playwright-cli --help

# 最小链路
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e15
playwright-cli screenshot

🚀 安装与最小工作流 >>>

先把工具装起来，再按“打开页面 -> 获取引用 -> 操作页面 -> 导出结果”走。它很像给浏览器包了一层命令行状态机，每次命令都在同一个 browser session 里继续推进。

安装与帮助

# 全局安装
npm install -g @playwright/cli@latest

# 查看版本和帮助
playwright-cli --version
playwright-cli --help
playwright-cli --help open
playwright-cli --help snapshot

# 只临时执行
npx @playwright/cli@latest --help

安装 skill

# 给 Claude / agents 安装本地 skills
playwright-cli install --skills
playwright-cli install --skills=claude
playwright-cli install --skills=agents
npx skills add https://github.com/microsoft/playwright-cli --skill playwright-cli

标准起手式

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

# 2. 拿页面快照，获取 e15 / e21 这类元素引用
playwright-cli snapshot

# 3. 交互
playwright-cli click e15
playwright-cli type "Buy groceries"
playwright-cli press Enter

# 4. 导出结果
playwright-cli screenshot
playwright-cli state-save auth.json

什么时候该重新 snapshot

  • 页面跳转后
  • 点击后 DOM 大改或弹窗出现后
  • 切 tab / 切 session 后
  • e15

⚠️ 不要混淆 >>>

这张卡专门解决最常见误解。`playwright-cli` 和 `npx playwright` 都来自 Playwright 生态，但用途不同，命令面也不同。
主题playwright-clinpx playwright
包@playwright/cliplaywright / @playwright/test
入口playwright-clinpx playwright ...
核心目标给 agent / 人类做浏览器交互与会话控制跑测试、录制脚本、看报告、合并报告
典型命令open snapshot click state-savetest codegen show-report merge-reports
更像什么浏览器自动化 shell测试 runner CLI
# 这是 @playwright/cli
playwright-cli open https://example.com
playwright-cli snapshot

# 这是传统 Playwright 测试 CLI
npx playwright test
npx playwright codegen
  • playwright-cli
  • npx playwright

🗂️ 会话与浏览器启动 >>>

这个 CLI 的关键能力之一是 session。你可以把它理解成“给不同任务开不同浏览器工作区”，每个 session 都保留自己的 cookies、storage、tabs 和页面状态。

基础启动

# 默认 headless
playwright-cli open https://playwright.dev

# 有头模式
playwright-cli open https://playwright.dev --headed

# 指定浏览器 / channel
playwright-cli open https://playwright.dev --browser=chrome
playwright-cli open https://playwright.dev --browser=msedge
playwright-cli open https://playwright.dev --browser=firefox
playwright-cli open https://playwright.dev --browser=webkit

持久化与 profile

# 关闭浏览器即丢失 profile
playwright-cli open https://example.com

# 持久化 profile 到磁盘
playwright-cli open https://example.com --persistent

# 指定 profile 目录
playwright-cli open https://example.com --profile=.playwright/profiles/demo

多 session

# 默认 session
playwright-cli open https://playwright.dev

# 命名 session
playwright-cli -s=todo open https://demo.playwright.dev/todomvc/
playwright-cli -s=docs open https://playwright.dev

# 查看、关闭、强杀
playwright-cli list
playwright-cli close-all
playwright-cli kill-all

会话环境变量

# 让 agent 进程默认绑定某个 session
set PLAYWRIGHT_CLI_SESSION=todo-app
playwright-cli open https://example.com
  • -s=name：当前命令发给指定 session
  • --persistent：跨浏览器重启也保留数据
  • delete-data：删除当前 session 的数据目录

🖱️ 页面交互主链 >>>

日常最常用的一组命令。先用 `snapshot` 拿元素 ref，再围绕 ref 做点击、填写、悬停、拖拽。比盲写 selector 更稳，也更适合 agent。

导航与打开

playwright-cli open https://example.com
playwright-cli goto https://example.com/dashboard
playwright-cli go-back
playwright-cli go-forward
playwright-cli reload
playwright-cli close

snapshot 与元素 ref

# 全页快照
playwright-cli snapshot

# 存到文件
playwright-cli snapshot --filename=page.md

# 只截某个根元素
playwright-cli snapshot "#main"

# 限制深度，减少噪音
playwright-cli snapshot --depth=4

# 对某个已有 ref 再局部快照
playwright-cli snapshot e34

核心交互

playwright-cli click e15
playwright-cli dblclick e15
playwright-cli hover e15
playwright-cli fill e22 "user@example.com"
playwright-cli fill e22 "user@example.com" --submit
playwright-cli type "hello world"
playwright-cli select e31 value-a
playwright-cli check e40
playwright-cli uncheck e40
playwright-cli drag e12 e33
playwright-cli upload ./fixtures/demo.pdf

drop 拖放文件/数据

# 拖文件到目标元素
playwright-cli drop e15 --path=./fixtures/demo.pdf

# 拖 data 到目标元素
playwright-cli drop e15 --data="text/plain=hello world"

直接用 selector / locator

# CSS selector
playwright-cli click "#main > button.submit"

# Playwright locator
playwright-cli click "getByRole('button', { name: 'Submit' })"
playwright-cli click "getByTestId('submit-button')"

# 根据已有 ref 生成 locator
playwright-cli generate-locator e15
  • ref：> 语义 locator > CSS selector
  • fill：更像“清空后再填入”
  • type：更像“往当前可编辑元素键入”

⌨️ 键盘、鼠标、标签页 >>>

这一组适合处理复杂交互，例如键盘快捷键、拖动、滚轮、弹窗和多标签页切换。前端开发里可以把它类比成把 DevTools 的手工操作拆成一串可重复命令。

键盘

playwright-cli press Enter
playwright-cli press ArrowLeft
playwright-cli keydown Shift
playwright-cli keyup Shift

鼠标

playwright-cli mousemove 320 480
playwright-cli mousedown left
playwright-cli mouseup left
playwright-cli mousewheel 0 600

对话框

playwright-cli dialog-accept
playwright-cli dialog-accept "yes"
playwright-cli dialog-dismiss

标签页

playwright-cli tab-list
playwright-cli tab-new https://example.com
playwright-cli tab-select 1
playwright-cli tab-close 1

窗口尺寸

playwright-cli resize 1440 900
playwright-cli resize 390 844

💾 存储、网络与导出 >>>

这部分决定你能不能把“登录态、网络限制、截图产物”稳定带到下一轮自动化里。最常用的是 `state-save/state-load`、cookies、本地存储和截图 / pdf。

Storage State

# 保存整份认证状态
playwright-cli state-save auth.json

# 载入认证状态
playwright-cli state-load auth.json

Cookie

playwright-cli cookie-list
playwright-cli cookie-get sessionid
playwright-cli cookie-set theme dark
playwright-cli cookie-delete theme
playwright-cli cookie-clear

localStorage / sessionStorage

playwright-cli localstorage-list
playwright-cli localstorage-get token
playwright-cli localstorage-set theme dark
playwright-cli localstorage-delete theme
playwright-cli localstorage-clear

playwright-cli sessionstorage-list
playwright-cli sessionstorage-get draft
playwright-cli sessionstorage-set draft hello
playwright-cli sessionstorage-clear

网络控制（v0.1.10 起 network 拆分为多个子命令）

# 列出记录到的网络请求（v0.1.10+ 拆分为 requests）
playwright-cli requests

# 查看单条请求详情
playwright-cli request 3

# 提取请求/响应各部分（适合 pipe 到文件）
playwright-cli request-headers 3 --filename=headers.txt
playwright-cli request-body 3 --filename=body.json
playwright-cli response-headers 3
playwright-cli response-body 3

# Mock / 解除 mock
playwright-cli route "**/api/**"
playwright-cli route-list
playwright-cli unroute

# 切离线 / 在线
playwright-cli network-state-set offline
playwright-cli network-state-set online

导出结果

playwright-cli screenshot
playwright-cli screenshot e15
playwright-cli pdf
  • state-save
  • network-state-set offline
  • screenshot [target] pdf

🔍 调试、监控与 DevTools >>>

当自动化看起来“像是卡住了”时，先用 `show` 看 session，再用 `console`、`network`、`eval`、`tracing-*` 缩小问题范围。排障顺序固定下来，效率会高很多。

监控 session

# 打开 dashboard
playwright-cli show

Console / JS / 请求

playwright-cli console
playwright-cli console warning
# network 已拆分为编号命令（v0.1.10+）
playwright-cli requests
playwright-cli request 3
playwright-cli request-headers 3 --filename=headers.txt
playwright-cli request-body 3 --filename=body.json
playwright-cli response-headers 3
playwright-cli response-body 3
playwright-cli eval "() => document.title"
playwright-cli eval "(el) => el.textContent" e15
playwright-cli run-code "await page.goto('https://example.com')"

Dashboard 与标注

playwright-cli show
# 启动标注模式，用于 UI review / 设计反馈（v0.1.9+）
playwright-cli show --annotate

高亮与 locator 生成

# 对元素显示持续高亮覆盖层
playwright-cli highlight e15
playwright-cli highlight e15 --style="background:yellow;border:2px solid red"
playwright-cli highlight e15 --hide
playwright-cli highlight --hide
# 根据已有 ref 生成 Playwright locator
playwright-cli generate-locator e15

Trace / Video

playwright-cli tracing-start
playwright-cli tracing-stop
playwright-cli video-start
playwright-cli video-chapter "after-login"
playwright-cli video-stop

调试执行

playwright-cli pause-at tests/login.spec.ts:42
playwright-cli resume
playwright-cli step-over
  • show：更像 session dashboard，可观察 agent 在后台做什么
  • eval：做只读探查最轻，适合临时取属性、文本、状态
  • run-code：直接执行 Playwright 代码片段，能力最强，也最容易把会话改坏

⚙️ 配置文件与环境变量 >>>

配置文件本质上是把常用启动参数、上下文选项和输出策略固化下来。类比前端工程里的 `vite.config` 或 `playwright.config`，避免每次命令都手写一大串 flag。

配置文件位置

# 显式指定
playwright-cli --config .playwright/cli.config.json open https://example.com

# 默认位置
.playwright/cli.config.json

最小配置示例

{
  "browser": {
    "browserName": "chromium",
    "userDataDir": ".playwright/profile",
    "launchOptions": {
      "channel": "chrome",
      "headless": false
    },
    "contextOptions": {
      "viewport": { "width": 1440, "height": 900 }
    }
  },
  "outputDir": ".playwright/output",
  "outputMode": "file",
  "console": {
    "level": "warning"
  },
  "timeouts": {
    "action": 5000,
    "navigation": 60000
  },
  "testIdAttribute": "data-testid"
}

常看字段

  • browser.browserName chromium firefox webkit：/ /
  • browser.userDataDir：持久化 profile 目录
  • browser.launchOptions channel headless executablePath：、、 等
  • browser.contextOptions viewport：、权限、UA、locale 等
  • browser.cdpEndpoint：连已有 Chromium 会话
  • outputDir outputMode：产物目录与输出方式
  • network.allowedOrigins blockedOrigins：网络放行和限制
  • timeouts.action timeouts.navigation：默认超时
  • allowUnrestrictedFileAccess file://：文件上传 / 等边界开关

高频环境变量

PLAYWRIGHT_CLI_SESSION=todo-app
PLAYWRIGHT_MCP_BROWSER=chrome
PLAYWRIGHT_MCP_HEADLESS=false
PLAYWRIGHT_MCP_CDP_ENDPOINT=http://127.0.0.1:9222
PLAYWRIGHT_MCP_OUTPUT_DIR=.playwright/output
PLAYWRIGHT_MCP_PROXY_SERVER=http://127.0.0.1:7897
PLAYWRIGHT_MCP_TIMEOUT_ACTION=8000
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1280x720
  • PLAYWRIGHT_MCP_*
  • 长期固定参数优先写进配置文件；临时调试再用 env 覆盖

🧪 高频 Recipes >>>

下面这些 recipe 覆盖最常见的真实任务：临时探查页面、带登录态继续跑、连接已有浏览器、离线验证、交付截图和 PDF。混合风格文档的价值就在这里，不只是列命令，而是告诉你什么时候组合哪一组命令。

Recipe 1：临时探查一个页面

playwright-cli open https://example.com --headed
playwright-cli snapshot
playwright-cli eval "() => document.title"
playwright-cli screenshot
适合：
  • 快速看页面结构
  • 让 agent 拿到第一轮元素 ref

Recipe 2：录一个可复用登录态

playwright-cli open https://github.com/login --persistent
playwright-cli snapshot
# 后续人工或 agent 完成登录动作
playwright-cli state-save auth.json
后续复用：
playwright-cli open https://github.com
playwright-cli state-load auth.json
playwright-cli reload

Recipe 3：给不同任务分不同 session

playwright-cli -s=docs open https://playwright.dev
playwright-cli -s=app open https://example.com/app --persistent
playwright-cli list
playwright-cli show
适合：
  • 一个 session 看文档，一个 session 操作业务系统
  • 避免 cookies / localStorage 串味

Recipe 4：连接已有浏览器或远程端点

# 通过配置文件写 CDP
playwright-cli --config .playwright/cli.config.json open https://example.com
配置里常见写法：
{
  "browser": {
    "cdpEndpoint": "http://127.0.0.1:9222"
  }
}
适合：
  • 复用已打开浏览器
  • 让 agent 接管已有 Chromium 会话

Recipe 5：做离线 / mock / 截图交付

playwright-cli open https://example.com
playwright-cli route "**/api/**"
playwright-cli network-state-set offline
playwright-cli snapshot
playwright-cli screenshot
适合：
  • 验证前端离线文案
  • 做快速演示图

📌 Quick Ref >>>

最后这张卡只保留高频命令速记。忘了全流程时回上面，临时抄命令时直接看这里。

启动与会话

playwright-cli open [url]
playwright-cli open [url] --headed
playwright-cli open [url] --browser=chrome
playwright-cli open [url] --persistent
playwright-cli open [url] --profile=<dir>
playwright-cli list
playwright-cli close-all
playwright-cli kill-all

页面与元素

playwright-cli snapshot [element]
playwright-cli snapshot --filename=page.md
playwright-cli snapshot --depth=4
playwright-cli click <target>
playwright-cli fill <target> <text>
playwright-cli fill <target> <text> --submit
playwright-cli type <text>
playwright-cli hover <target>
playwright-cli drag <start> <end>
playwright-cli drop <target> --path=<file>
playwright-cli drop <target> --data="k=v"
playwright-cli upload <file>

导航与标签页

playwright-cli goto <url>
playwright-cli go-back
playwright-cli go-forward
playwright-cli reload
playwright-cli tab-list
playwright-cli tab-new [url]
playwright-cli tab-select <index>
playwright-cli tab-close [index]

存储与导出

playwright-cli state-save [file]
playwright-cli state-load <file>
playwright-cli cookie-list
playwright-cli localstorage-list
playwright-cli sessionstorage-list
playwright-cli screenshot [target]
playwright-cli pdf

调试与可视化

playwright-cli show
playwright-cli show --annotate
playwright-cli console [level]
playwright-cli requests
playwright-cli request <num>
playwright-cli eval <func> [element]
playwright-cli run-code <code>
playwright-cli highlight <ref> [--style=] [--hide]
playwright-cli generate-locator <ref>
playwright-cli tracing-start
playwright-cli tracing-stop
playwright-cli video-start [file]
playwright-cli video-stop

🩹 决策点与常见坑 >>>

真正容易踩坑的地方，不是命令拼写，而是会话边界、ref 生命周期、持久化策略和工具混淆。先把这些规则立住，后面的命令基本都顺。
  • playwright-cli npx playwright
  • snapshot
  • --persistent
  • run-code
  • state-save/state-load
  • -s=name
  • outputDir outputMode

不要混淆：playwright-cli vs agent-browser

playwright-cliagent-browser
出品方MicrosoftVercel Labs
元素引用语法e15（纯数字后缀）@e1（at-e1）
连接已有浏览器--cdp via 配置文件--auto-connect（推荐）/ --cdp 9222（手动）
Provider 生态传统 Playwright ProviderBrowserbase、Browserless、Kernel、AgentCore、iOS 模拟器等
AI 集成无v0.25.0+ 内嵌 chat 命令
OAuth MCP无支持（v0.24.0+）
适用场景测试驱动、session 状态管理、Playwright 生态深度用户AI agent 驱动、需要会话复用、云端浏览器、多 Provider
两者功能有较大重叠（open/snapshot/click/fill/screenshot 等），但定位不同：
  • playwright-cli 更适合测试和 Playwright 生态深度用户，强调 session/profile 管理和传统测试工作流
  • agent-browser 更适合 AI agent 场景，强调会话复用、Provider 生态、OAuth MCP 和自然语言交互

🧾 版本变更 >>>

按官方发布说明整理本次跨版本更新中对速查用户最重要的变化。

v0.1.13

  • fix(mcp): forward browser-level CDP commands in extension mode cookie-list state-save

v0.1.12

  • tab-new tab-list
  • Dashboard 新增多截图 UI Review 功能，支持收集、标注、在一个 session 内提交多张截图，带侧边栏帧列表和逐条高亮

v0.1.11

  • fix(dashboard): handle null viewport in annotate screenshot viewport: null window.innerWidth/innerHeight

v0.1.10

  • network
    • requests
    • request <num>
    • request-headers request-body response-headers response-body
    • --filename

v0.1.9

  • show --annotate
  • drop

v0.1.8

  • 新增远程调试模式，可连接本地已有 Chrome（带已有登录态），不再使用沙盒副本
  • playwright-cli attach --cdp=chrome msedge chrome-canary chrome://inspect/#remote-debugging
    • 支持 Chrome / Chrome Beta / Dev / Canary 和 Edge / Edge Beta / Dev / Canary（Linux、macOS、Windows）