wehub-skill-sync
210 lines
9.4 KiB
Markdown
210 lines
9.4 KiB
Markdown
---
|
||
name: playwright-cli
|
||
description: 使用 playwright-cli 自动化浏览器交互，用于 Web 测试、表单填写、截图和数据提取。当用户需要浏览网站、与网页交互、填写表单、截图、测试 Web 应用、从网页提取信息、模拟网络请求、管理浏览器会话或生成测试代码时使用。
|
||
allowed-tools: Bash(playwright-cli:*)
|
||
---
|
||
|
||
# 使用 playwright-cli 的浏览器自动化
|
||
|
||
> 全面的 CLI 驱动浏览器自动化——导航、交互、模拟、调试、录制和生成测试，无需编写任何脚本文件。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装与设置
|
||
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 和存储
|
||
|
||
## 命令参考
|
||
|
||
### 核心交互
|
||
|
||
```bash
|
||
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 # 关闭浏览器
|
||
```
|
||
|
||
### 导航
|
||
|
||
```bash
|
||
playwright-cli go-back # 浏览器后退
|
||
playwright-cli go-forward # 浏览器前进
|
||
playwright-cli reload # 刷新当前页面
|
||
```
|
||
|
||
### 键盘与鼠标
|
||
|
||
```bash
|
||
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）
|
||
```
|
||
|
||
### 对话框
|
||
|
||
```bash
|
||
playwright-cli dialog-accept # 接受 alert/confirm/prompt
|
||
playwright-cli dialog-accept "text" # 接受 prompt 并输入文本
|
||
playwright-cli dialog-dismiss # 关闭/取消对话框
|
||
```
|
||
|
||
### 标签页
|
||
|
||
```bash
|
||
playwright-cli tab-list # 列出所有打开的标签页
|
||
playwright-cli tab-new [url] # 打开新标签页
|
||
playwright-cli tab-select <index> # 按索引切换标签页
|
||
playwright-cli tab-close [index] # 关闭标签页（当前或按索引）
|
||
```
|
||
|
||
### 截图与媒体
|
||
|
||
```bash
|
||
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 # 调整视口大小
|
||
```
|
||
|
||
### 存储与认证
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 网络模拟
|
||
|
||
```bash
|
||
playwright-cli route "<pattern>" [opts] # 拦截匹配的请求
|
||
playwright-cli route-list # 列出活跃的路由覆盖规则
|
||
playwright-cli unroute "<pattern>" # 移除特定路由规则
|
||
playwright-cli unroute # 移除所有路由规则
|
||
```
|
||
|
||
### DevTools 与调试
|
||
|
||
```bash
|
||
playwright-cli console [level] # 显示控制台消息
|
||
playwright-cli network # 显示网络请求
|
||
playwright-cli tracing-start # 开始记录追踪
|
||
playwright-cli tracing-stop # 停止并保存追踪
|
||
playwright-cli run-code "async page => {}" # 执行 Playwright API 代码
|
||
```
|
||
|
||
### 会话与配置
|
||
|
||
```bash
|
||
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](core-commands.md) |
|
||
| 生成测试代码 | [test-generation.md](test-generation.md) |
|
||
| 截图、视频、PDF | [screenshots-and-media.md](screenshots-and-media.md) |
|
||
|
||
### 测试与调试
|
||
|
||
| 你要做的事情 | 指南 |
|
||
| ----------------------------- | --------------------------------------------------- |
|
||
| 追踪与调试 | [tracing-and-debugging.md](tracing-and-debugging.md) |
|
||
| 网络模拟与拦截 | [request-mocking.md](request-mocking.md) |
|
||
| 运行自定义 Playwright 代码 | [running-custom-code.md](running-custom-code.md) |
|
||
|
||
### 状态与会话
|
||
|
||
| 你要做的事情 | 指南 |
|
||
| ---------------------------------- | --------------------------------------------- |
|
||
| Cookie、localStorage、认证状态 | [storage-and-auth.md](storage-and-auth.md) |
|
||
| 多会话管理 | [session-management.md](session-management.md) |
|
||
|
||
### 高级
|
||
|
||
| 你要做的事情 | 指南 |
|
||
| ----------------------------- | --------------------------------------------- |
|
||
| 设备与环境模拟 | [device-emulation.md](device-emulation.md) |
|
||
| 复杂多步骤工作流 | [advanced-workflows.md](advanced-workflows.md) |
|