skillhub-147-playwright-skill/playwright-cli/core-commands.md

核心命令

适用场景：通过 CLI 启动浏览器自动化会话、浏览页面、与元素交互、填写表单以及执行基本浏览器操作。 前置条件：playwright-cli install --skills && playwright-cli install-browser

快速参考

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）。

playwright-cli open https://example.com/login
playwright-cli snapshot
# 输出：
# e1 [textbox "邮箱"]
# e2 [textbox "密码"]
# e3 [button "登录"]
# e4 [link "忘记密码？"]
# e5 [link "创建账号"]

使用引用来精确定位元素：

playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "secretpassword"
playwright-cli click e3

页面变化后务必重新截图——引用仅对当前页面状态有效。在导航、表单提交或动态内容更新后，应重新生成快照。

playwright-cli click e3          # 提交表单
playwright-cli snapshot          # 重新截图以查看新页面元素

保存快照

将快照保存为 YAML 文件，以便后续参考或对比：

playwright-cli snapshot --filename=before-submit.yaml
playwright-cli click e3
playwright-cli snapshot --filename=after-submit.yaml

打开与关闭浏览器

基本启动

# 打开浏览器，显示空白页面
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 可在重启后保持状态：

# 自动生成的配置目录
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

浏览器扩展模式

通过扩展连接到现有浏览器，而非启动新浏览器：

playwright-cli open --extension

关闭

playwright-cli close              # 关闭当前浏览器
playwright-cli close-all          # 关闭所有已打开的浏览器
playwright-cli kill-all           # 强制杀死僵尸进程
playwright-cli delete-data        # 删除已存储的配置数据

导航

playwright-cli goto https://example.com/dashboard    # 跳转到 URL
playwright-cli go-back                                # 浏览器后退
playwright-cli go-forward                             # 浏览器前进
playwright-cli reload                                 # 刷新页面

等待导航

在执行触发导航的操作（表单提交、链接点击）后，CLI 会等待页面达到 load 状态后再返回。如果需要等待特定条件，可使用 run-code：

playwright-cli run-code "async page => {
  await page.waitForURL('**/dashboard');
}"

# 等待网络空闲
playwright-cli run-code "async page => {
  await page.waitForLoadState('networkidle');
}"

元素交互

点击

playwright-cli click e3            # 标准左键单击
playwright-cli dblclick e7         # 双击
playwright-cli hover e4            # 悬停（不点击）

表单输入

# 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 事件的自定义输入

文件上传

playwright-cli upload e8 ./document.pdf
playwright-cli upload e8 ./photo1.jpg ./photo2.jpg    # 多文件

拖放

playwright-cli drag e2 e8    # 将元素 e2 拖放到元素 e8 上

视口调整

playwright-cli resize 1920 1080    # 桌面端
playwright-cli resize 375 812      # iPhone X 视口
playwright-cli resize 768 1024     # iPad 视口

键盘输入

单键按下

playwright-cli press Enter
playwright-cli press Tab
playwright-cli press Escape
playwright-cli press Backspace
playwright-cli press Delete
playwright-cli press Space

方向键

playwright-cli press ArrowUp
playwright-cli press ArrowDown
playwright-cli press ArrowLeft
playwright-cli press ArrowRight

修饰键组合

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

按键保持与释放

用于拖拽操作或多键序列：

playwright-cli keydown Shift
playwright-cli click e5              # Shift+点击
playwright-cli click e8              # Shift+点击（范围选择）
playwright-cli keyup Shift

鼠标控制

用于像素级精确操作（画布、地图、自定义控件）：

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

在画布上绘制

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）会阻塞浏览器交互，需立即处理：

# 接受 alert 或 confirm 对话框
playwright-cli dialog-accept

# 接受 prompt 对话框并输入文本
playwright-cli dialog-accept "my response"

# 驳回/取消对话框
playwright-cli dialog-dismiss

提示：如果预期某个点击会触发对话框，可在触发操作前通过 run-code 配置处理逻辑：

playwright-cli run-code "async page => {
  page.on('dialog', dialog => dialog.accept('confirmed'));
}"
playwright-cli click e5    # 此操作会触发对话框

JavaScript 求值

在页面上下文中直接执行 JavaScript 表达式：

# 简单表达式
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"

示例工作流

登录流程

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

含验证的表单提交

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

搜索结果浏览

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

多标签研究

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 错误