--- 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 # 导航到指定网址 playwright-cli snapshot # 显示带引用编号的页面元素 playwright-cli snapshot --filename=snap.yaml # 将快照保存到文件 playwright-cli click # 点击元素 playwright-cli dblclick # 双击 playwright-cli fill "value" # 清空并填写输入框 playwright-cli type "text" # 逐个按键输入文本 playwright-cli select "option-value" # 选择下拉选项 playwright-cli check # 勾选复选框 playwright-cli uncheck # 取消勾选复选框 playwright-cli hover # 悬停在元素上 playwright-cli drag # 拖放操作 playwright-cli upload ./file.pdf # 上传文件 playwright-cli eval "document.title" # 执行 JS 表达式 playwright-cli eval "el => el.textContent" # 在元素上执行表达式 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 # 按索引切换标签页 playwright-cli tab-close [index] # 关闭标签页（当前或按索引） ``` ### 截图与媒体 ```bash playwright-cli screenshot # 截取当前页面截图 playwright-cli screenshot # 截取指定元素的截图 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 # 恢复已保存的状态 playwright-cli cookie-list [--domain=...] # 列出 cookie playwright-cli cookie-get # 获取指定 cookie playwright-cli cookie-set [opts] # 设置 cookie playwright-cli cookie-delete # 删除 cookie playwright-cli cookie-clear # 清除所有 cookie playwright-cli localstorage-list # 列出 localStorage 项 playwright-cli localstorage-get # 获取 localStorage 值 playwright-cli localstorage-set # 设置 localStorage 值 playwright-cli localstorage-delete # 删除 localStorage 项 playwright-cli localstorage-clear # 清除所有 localStorage playwright-cli sessionstorage-list # 列出 sessionStorage playwright-cli sessionstorage-get # 获取 sessionStorage 值 playwright-cli sessionstorage-set # 设置 sessionStorage 值 playwright-cli sessionstorage-delete # 删除 sessionStorage 项 playwright-cli sessionstorage-clear # 清除所有 sessionStorage ``` ### 网络模拟 ```bash playwright-cli route "" [opts] # 拦截匹配的请求 playwright-cli route-list # 列出活跃的路由覆盖规则 playwright-cli unroute "" # 移除特定路由规则 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= # 在命名会话中执行命令 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) |