skillhub-147-playwright-skill/playwright-cli/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
playwright-cli	使用 playwright-cli 自动化浏览器交互，用于 Web 测试、表单填写、截图和数据提取。当用户需要浏览网站、与网页交互、填写表单、截图、测试 Web 应用、从网页提取信息、模拟网络请求、管理浏览器会话或生成测试代码时使用。	Bash(playwright-cli:*)

使用 playwright-cli 的浏览器自动化

全面的 CLI 驱动浏览器自动化——导航、交互、模拟、调试、录制和生成测试，无需编写任何脚本文件。

快速开始

# 安装与设置
playwright-cli install --skills
playwright-cli install-browser

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

# 截取快照以查看可交互元素（引用如 e1、e2、e3……）
playwright-cli snapshot

# 使用快照中的元素引用进行交互
playwright-cli click e15
playwright-cli fill e5 "search query"
playwright-cli press Enter

# 截图
playwright-cli screenshot

# 关闭浏览器
playwright-cli close

黄金法则

1. 始终先执行 snapshot——在交互前先识别元素引用；切勿猜测引用编号
2. 输入用 fill，按钮用 click——type 逐个发送按键，fill 替换整个值
3. 并行工作使用命名会话——-s=name 按会话隔离 cookie、存储和标签页
4. 保存认证状态——登录后执行 state-save auth.json，下次使用 state-load auth.json 跳过登录
5. 调试前先追踪——在失败的步骤之前执行 tracing-start，而非之后
6. 高级场景使用 run-code——当 CLI 命令不足时，直接使用完整的 Playwright API
7. 清理会话——完成后执行 close 或 close-all；对僵尸进程使用 kill-all
8. 文件名要有描述性——screenshot --filename=checkout-step3.png，而非 screenshot
9. 仅模拟外部 API——使用 route 拦截第三方服务，而非你自己的应用
10. 有状态流程使用持久化配置——--persistent 在重启之间保留 cookie 和存储

命令参考

核心交互

playwright-cli open [url]                    # 启动浏览器，可选导航到网址
playwright-cli goto <url>                    # 导航到指定网址
playwright-cli snapshot                      # 显示带引用编号的页面元素
playwright-cli snapshot --filename=snap.yaml # 将快照保存到文件
playwright-cli click <ref>                   # 点击元素
playwright-cli dblclick <ref>                # 双击
playwright-cli fill <ref> "value"            # 清空并填写输入框
playwright-cli type "text"                   # 逐个按键输入文本
playwright-cli select <ref> "option-value"   # 选择下拉选项
playwright-cli check <ref>                   # 勾选复选框
playwright-cli uncheck <ref>                 # 取消勾选复选框
playwright-cli hover <ref>                   # 悬停在元素上
playwright-cli drag <src-ref> <dst-ref>      # 拖放操作
playwright-cli upload <ref> ./file.pdf       # 上传文件
playwright-cli eval "document.title"         # 执行 JS 表达式
playwright-cli eval "el => el.textContent" <ref>  # 在元素上执行表达式
playwright-cli close                         # 关闭浏览器

导航

playwright-cli go-back                       # 浏览器后退
playwright-cli go-forward                    # 浏览器前进
playwright-cli reload                        # 刷新当前页面

键盘与鼠标

playwright-cli press Enter                   # 按下按键
playwright-cli press ArrowDown               # 方向键
playwright-cli keydown Shift                 # 按住按键
playwright-cli keyup Shift                   # 释放按键
playwright-cli mousemove 150 300             # 移动鼠标到坐标
playwright-cli mousedown [right]             # 按下鼠标按钮
playwright-cli mouseup [right]               # 释放鼠标按钮
playwright-cli mousewheel 0 100              # 滚动（deltaX, deltaY）

对话框

playwright-cli dialog-accept                 # 接受 alert/confirm/prompt
playwright-cli dialog-accept "text"          # 接受 prompt 并输入文本
playwright-cli dialog-dismiss                # 关闭/取消对话框

标签页

playwright-cli tab-list                      # 列出所有打开的标签页
playwright-cli tab-new [url]                 # 打开新标签页
playwright-cli tab-select <index>            # 按索引切换标签页
playwright-cli tab-close [index]             # 关闭标签页（当前或按索引）

截图与媒体

playwright-cli screenshot                    # 截取当前页面截图
playwright-cli screenshot <ref>              # 截取指定元素的截图
playwright-cli screenshot --filename=pg.png  # 使用自定义文件名保存
playwright-cli pdf --filename=page.pdf       # 将页面保存为 PDF
playwright-cli video-start                   # 开始录制视频
playwright-cli video-stop output.webm        # 停止并保存视频
playwright-cli resize 1920 1080              # 调整视口大小

存储与认证

playwright-cli state-save [file.json]        # 保存 cookie + localStorage
playwright-cli state-load <file.json>        # 恢复已保存的状态
playwright-cli cookie-list [--domain=...]    # 列出 cookie
playwright-cli cookie-get <name>             # 获取指定 cookie
playwright-cli cookie-set <name> <value> [opts]  # 设置 cookie
playwright-cli cookie-delete <name>          # 删除 cookie
playwright-cli cookie-clear                  # 清除所有 cookie
playwright-cli localstorage-list             # 列出 localStorage 项
playwright-cli localstorage-get <key>        # 获取 localStorage 值
playwright-cli localstorage-set <key> <val>  # 设置 localStorage 值
playwright-cli localstorage-delete <key>     # 删除 localStorage 项
playwright-cli localstorage-clear            # 清除所有 localStorage
playwright-cli sessionstorage-list           # 列出 sessionStorage
playwright-cli sessionstorage-get <key>      # 获取 sessionStorage 值
playwright-cli sessionstorage-set <key> <val>    # 设置 sessionStorage 值
playwright-cli sessionstorage-delete <key>   # 删除 sessionStorage 项
playwright-cli sessionstorage-clear          # 清除所有 sessionStorage

网络模拟

playwright-cli route "<pattern>" [opts]      # 拦截匹配的请求
playwright-cli route-list                    # 列出活跃的路由覆盖规则
playwright-cli unroute "<pattern>"           # 移除特定路由规则
playwright-cli unroute                       # 移除所有路由规则

DevTools 与调试

playwright-cli console [level]              # 显示控制台消息
playwright-cli network                      # 显示网络请求
playwright-cli tracing-start                # 开始记录追踪
playwright-cli tracing-stop                 # 停止并保存追踪
playwright-cli run-code "async page => {}"  # 执行 Playwright API 代码

会话与配置

playwright-cli -s=<name> <command>          # 在命名会话中执行命令
playwright-cli list                         # 列出所有活跃会话
playwright-cli close-all                    # 关闭所有浏览器
playwright-cli kill-all                     # 强制终止所有进程
playwright-cli delete-data                  # 删除会话用户数据
playwright-cli open --browser=firefox       # 使用指定浏览器
playwright-cli open --persistent            # 将配置文件持久化到磁盘
playwright-cli open --profile=/path         # 自定义配置文件目录
playwright-cli open --config=config.json    # 使用配置文件
playwright-cli open --extension             # 通过扩展连接

指南索引

入门

你要做的事情	指南
核心浏览器交互	core-commands.md
生成测试代码	test-generation.md
截图、视频、PDF	screenshots-and-media.md

测试与调试

你要做的事情	指南
追踪与调试	tracing-and-debugging.md
网络模拟与拦截	request-mocking.md
运行自定义 Playwright 代码	running-custom-code.md

状态与会话

你要做的事情	指南
Cookie、localStorage、认证状态	storage-and-auth.md
多会话管理	session-management.md

高级

你要做的事情	指南
设备与环境模拟	device-emulation.md
复杂多步骤工作流	advanced-workflows.md