wehub-skill-sync
376 lines
10 KiB
Markdown
376 lines
10 KiB
Markdown
# 核心命令
|
||
|
||
> **适用场景**：通过 CLI 启动浏览器自动化会话、浏览页面、与元素交互、填写表单以及执行基本浏览器操作。
|
||
> **前置条件**：`playwright-cli install --skills && playwright-cli install-browser`
|
||
|
||
## 快速参考
|
||
|
||
```bash
|
||
playwright-cli open https://example.com # 启动并跳转
|
||
playwright-cli snapshot # 查看所有可交互元素
|
||
playwright-cli fill e1 "user@example.com" # 填写输入框
|
||
playwright-cli click e3 # 点击按钮
|
||
playwright-cli screenshot --filename=pg.png # 截取页面截图
|
||
playwright-cli close # 完成
|
||
```
|
||
|
||
## 快照工作流
|
||
|
||
每次交互都从**快照**开始。`snapshot` 命令会渲染页面的无障碍树，并为每个可交互元素分配简短的引用（如 `e1`、`e2`、`e3`）。
|
||
|
||
```bash
|
||
playwright-cli open https://example.com/login
|
||
playwright-cli snapshot
|
||
# 输出：
|
||
# e1 [textbox "邮箱"]
|
||
# e2 [textbox "密码"]
|
||
# e3 [button "登录"]
|
||
# e4 [link "忘记密码？"]
|
||
# e5 [link "创建账号"]
|
||
```
|
||
|
||
使用引用来精确定位元素：
|
||
|
||
```bash
|
||
playwright-cli fill e1 "user@example.com"
|
||
playwright-cli fill e2 "secretpassword"
|
||
playwright-cli click e3
|
||
```
|
||
|
||
**页面变化后务必重新截图**——引用仅对当前页面状态有效。在导航、表单提交或动态内容更新后，应重新生成快照。
|
||
|
||
```bash
|
||
playwright-cli click e3 # 提交表单
|
||
playwright-cli snapshot # 重新截图以查看新页面元素
|
||
```
|
||
|
||
### 保存快照
|
||
|
||
将快照保存为 YAML 文件，以便后续参考或对比：
|
||
|
||
```bash
|
||
playwright-cli snapshot --filename=before-submit.yaml
|
||
playwright-cli click e3
|
||
playwright-cli snapshot --filename=after-submit.yaml
|
||
```
|
||
|
||
## 打开与关闭浏览器
|
||
|
||
### 基本启动
|
||
|
||
```bash
|
||
# 打开浏览器，显示空白页面
|
||
playwright-cli open
|
||
|
||
# 打开并立即跳转
|
||
playwright-cli open https://example.com
|
||
|
||
# 使用特定浏览器引擎打开
|
||
playwright-cli open --browser=chrome # Google Chrome
|
||
playwright-cli open --browser=firefox # Mozilla Firefox
|
||
playwright-cli open --browser=webkit # Safari/WebKit
|
||
playwright-cli open --browser=msedge # Microsoft Edge
|
||
```
|
||
|
||
### 持久化配置
|
||
|
||
默认情况下，每个会话在内存中运行——关闭后不会保留 Cookie 或存储数据。使用 `--persistent` 可在重启后保持状态：
|
||
|
||
```bash
|
||
# 自动生成的配置目录
|
||
playwright-cli open https://example.com --persistent
|
||
|
||
# 自定义配置目录
|
||
playwright-cli open https://example.com --profile=/tmp/my-profile
|
||
|
||
# 使用配置文件
|
||
playwright-cli open https://example.com --config=my-config.json
|
||
```
|
||
|
||
### 浏览器扩展模式
|
||
|
||
通过扩展连接到现有浏览器，而非启动新浏览器：
|
||
|
||
```bash
|
||
playwright-cli open --extension
|
||
```
|
||
|
||
### 关闭
|
||
|
||
```bash
|
||
playwright-cli close # 关闭当前浏览器
|
||
playwright-cli close-all # 关闭所有已打开的浏览器
|
||
playwright-cli kill-all # 强制杀死僵尸进程
|
||
playwright-cli delete-data # 删除已存储的配置数据
|
||
```
|
||
|
||
## 导航
|
||
|
||
```bash
|
||
playwright-cli goto https://example.com/dashboard # 跳转到 URL
|
||
playwright-cli go-back # 浏览器后退
|
||
playwright-cli go-forward # 浏览器前进
|
||
playwright-cli reload # 刷新页面
|
||
```
|
||
|
||
### 等待导航
|
||
|
||
在执行触发导航的操作（表单提交、链接点击）后，CLI 会等待页面达到 `load` 状态后再返回。如果需要等待特定条件，可使用 `run-code`：
|
||
|
||
```bash
|
||
playwright-cli run-code "async page => {
|
||
await page.waitForURL('**/dashboard');
|
||
}"
|
||
|
||
# 等待网络空闲
|
||
playwright-cli run-code "async page => {
|
||
await page.waitForLoadState('networkidle');
|
||
}"
|
||
```
|
||
|
||
## 元素交互
|
||
|
||
### 点击
|
||
|
||
```bash
|
||
playwright-cli click e3 # 标准左键单击
|
||
playwright-cli dblclick e7 # 双击
|
||
playwright-cli hover e4 # 悬停（不点击）
|
||
```
|
||
|
||
### 表单输入
|
||
|
||
```bash
|
||
# fill：清除现有值，然后一次性输入完整值
|
||
playwright-cli fill e5 "user@example.com"
|
||
|
||
# type：逐个发送按键事件（每个字符触发 keydown/keypress/keyup）
|
||
playwright-cli type "search query"
|
||
|
||
# select：按值选择下拉选项
|
||
playwright-cli select e9 "option-value"
|
||
|
||
# check/uncheck：勾选/取消勾选复选框
|
||
playwright-cli check e12
|
||
playwright-cli uncheck e12
|
||
```
|
||
|
||
**何时使用 `fill` 与 `type`**：
|
||
|
||
| 命令 | 行为 | 适用场景 |
|
||
| -------- | ------------------------------ | ---------------------------------------------- |
|
||
| `fill` | 清除字段，一次性设置值 | 表单、登录字段、标准输入框 |
|
||
| `type` | 逐个发送按键事件 | 自动补全、即输即搜、监听 keydown 事件的自定义输入 |
|
||
|
||
### 文件上传
|
||
|
||
```bash
|
||
playwright-cli upload e8 ./document.pdf
|
||
playwright-cli upload e8 ./photo1.jpg ./photo2.jpg # 多文件
|
||
```
|
||
|
||
### 拖放
|
||
|
||
```bash
|
||
playwright-cli drag e2 e8 # 将元素 e2 拖放到元素 e8 上
|
||
```
|
||
|
||
### 视口调整
|
||
|
||
```bash
|
||
playwright-cli resize 1920 1080 # 桌面端
|
||
playwright-cli resize 375 812 # iPhone X 视口
|
||
playwright-cli resize 768 1024 # iPad 视口
|
||
```
|
||
|
||
## 键盘输入
|
||
|
||
### 单键按下
|
||
|
||
```bash
|
||
playwright-cli press Enter
|
||
playwright-cli press Tab
|
||
playwright-cli press Escape
|
||
playwright-cli press Backspace
|
||
playwright-cli press Delete
|
||
playwright-cli press Space
|
||
```
|
||
|
||
### 方向键
|
||
|
||
```bash
|
||
playwright-cli press ArrowUp
|
||
playwright-cli press ArrowDown
|
||
playwright-cli press ArrowLeft
|
||
playwright-cli press ArrowRight
|
||
```
|
||
|
||
### 修饰键组合
|
||
|
||
```bash
|
||
playwright-cli press Control+a # 全选
|
||
playwright-cli press Control+c # 复制
|
||
playwright-cli press Control+v # 粘贴
|
||
playwright-cli press Control+z # 撤销
|
||
playwright-cli press Meta+a # 全选（macOS 下为 Cmd+A）
|
||
playwright-cli press Shift+Tab # 反向切换焦点
|
||
playwright-cli press Alt+Enter # Alt+Enter
|
||
```
|
||
|
||
### 按键保持与释放
|
||
|
||
用于拖拽操作或多键序列：
|
||
|
||
```bash
|
||
playwright-cli keydown Shift
|
||
playwright-cli click e5 # Shift+点击
|
||
playwright-cli click e8 # Shift+点击（范围选择）
|
||
playwright-cli keyup Shift
|
||
```
|
||
|
||
## 鼠标控制
|
||
|
||
用于像素级精确操作（画布、地图、自定义控件）：
|
||
|
||
```bash
|
||
playwright-cli mousemove 150 300 # 将光标移动到指定坐标
|
||
playwright-cli mousedown # 按下左键
|
||
playwright-cli mouseup # 释放左键
|
||
playwright-cli mousedown right # 按下右键
|
||
playwright-cli mouseup right # 释放右键
|
||
playwright-cli mousewheel 0 100 # 向下滚动 100px
|
||
playwright-cli mousewheel 0 -100 # 向上滚动 100px
|
||
playwright-cli mousewheel 100 0 # 向右滚动 100px
|
||
```
|
||
|
||
### 在画布上绘制
|
||
|
||
```bash
|
||
playwright-cli open https://example.com/canvas-app
|
||
playwright-cli mousemove 100 100
|
||
playwright-cli mousedown
|
||
playwright-cli mousemove 200 200
|
||
playwright-cli mousemove 300 150
|
||
playwright-cli mouseup
|
||
```
|
||
|
||
## 对话框处理
|
||
|
||
对话框（`alert`、`confirm`、`prompt`）会阻塞浏览器交互，需立即处理：
|
||
|
||
```bash
|
||
# 接受 alert 或 confirm 对话框
|
||
playwright-cli dialog-accept
|
||
|
||
# 接受 prompt 对话框并输入文本
|
||
playwright-cli dialog-accept "my response"
|
||
|
||
# 驳回/取消对话框
|
||
playwright-cli dialog-dismiss
|
||
```
|
||
|
||
**提示**：如果预期某个点击会触发对话框，可在触发操作前通过 `run-code` 配置处理逻辑：
|
||
|
||
```bash
|
||
playwright-cli run-code "async page => {
|
||
page.on('dialog', dialog => dialog.accept('confirmed'));
|
||
}"
|
||
playwright-cli click e5 # 此操作会触发对话框
|
||
```
|
||
|
||
## JavaScript 求值
|
||
|
||
在页面上下文中直接执行 JavaScript 表达式：
|
||
|
||
```bash
|
||
# 简单表达式
|
||
playwright-cli eval "document.title"
|
||
playwright-cli eval "window.location.href"
|
||
playwright-cli eval "document.querySelectorAll('li').length"
|
||
|
||
# 对特定元素求值
|
||
playwright-cli eval "el => el.textContent" e5
|
||
playwright-cli eval "el => el.getAttribute('href')" e3
|
||
playwright-cli eval "el => el.getBoundingClientRect()" e1
|
||
|
||
# 复杂求值
|
||
playwright-cli eval "JSON.stringify(performance.timing)"
|
||
playwright-cli eval "window.innerWidth + 'x' + window.innerHeight"
|
||
```
|
||
|
||
## 示例工作流
|
||
|
||
### 登录流程
|
||
|
||
```bash
|
||
playwright-cli open https://app.example.com/login
|
||
playwright-cli snapshot
|
||
|
||
playwright-cli fill e1 "admin@example.com"
|
||
playwright-cli fill e2 "password123"
|
||
playwright-cli click e3
|
||
playwright-cli snapshot # 查看仪表盘
|
||
playwright-cli screenshot --filename=dashboard.png
|
||
playwright-cli close
|
||
```
|
||
|
||
### 含验证的表单提交
|
||
|
||
```bash
|
||
playwright-cli open https://example.com/contact
|
||
playwright-cli snapshot
|
||
|
||
# 填写表单字段
|
||
playwright-cli fill e1 "Jane Doe"
|
||
playwright-cli fill e2 "jane@example.com"
|
||
playwright-cli fill e3 "+1-555-0123"
|
||
playwright-cli select e4 "support"
|
||
playwright-cli fill e5 "I need help with my account"
|
||
playwright-cli check e6 # 同意条款
|
||
|
||
# 提交
|
||
playwright-cli click e7
|
||
playwright-cli snapshot # 验证成功消息
|
||
playwright-cli close
|
||
```
|
||
|
||
### 搜索结果浏览
|
||
|
||
```bash
|
||
playwright-cli open https://example.com
|
||
playwright-cli snapshot
|
||
|
||
playwright-cli fill e1 "playwright automation"
|
||
playwright-cli press Enter
|
||
playwright-cli snapshot # 查看搜索结果
|
||
|
||
playwright-cli click e5 # 点击第一个结果
|
||
playwright-cli snapshot # 查看结果页
|
||
playwright-cli go-back # 返回搜索结果
|
||
playwright-cli close
|
||
```
|
||
|
||
### 多标签研究
|
||
|
||
```bash
|
||
playwright-cli open https://docs.example.com
|
||
playwright-cli tab-new https://api.example.com/reference
|
||
playwright-cli tab-new https://github.com/example/repo
|
||
|
||
playwright-cli tab-list # 查看所有 3 个标签页
|
||
playwright-cli tab-select 0 # 切换到文档标签页
|
||
playwright-cli snapshot
|
||
playwright-cli tab-select 2 # 切换到 GitHub 标签页
|
||
playwright-cli snapshot
|
||
|
||
playwright-cli close # 关闭所有标签页
|
||
```
|
||
|
||
## 小贴士
|
||
|
||
- **频繁截图**：每次页面发生变化后，重新截图以获取最新引用
|
||
- **表单使用 `fill`**：对于标准输入，`fill` 比 `type` 更快更可靠
|
||
- **注意视口**：截图前使用 `resize` 测试响应式布局
|
||
- **结合 `run-code`**：当 CLI 命令受限时，可直接使用完整的 Playwright API
|
||
- **检查 `console`**：运行 `playwright-cli console` 查看可能解释异常行为的 JavaScript 错误
|