# 核心命令

> **适用场景**：通过 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 错误