Clawbrowser – 通过Playwright CLI控制浏览器

设置与入门指南

1. 安装CLI并验证可用性：

   npm install -g @playwright/cli@latest
   playwright-cli --help
   

   CLI默认以无头模式运行；当您需要查看用户界面时，请在open命令中添加--headed参数，或在playwright-cli.json配置文件中将browser.launchOptions.headless设置为false。
2. CLI默认读取playwright-cli.json配置文件，或通过--config参数指定其他配置文件。通过配置文件可统一调整浏览器名称、启动/上下文选项、视窗尺寸、超时设置、输出目录和录制设置，无需修改每条命令。
3. 随时使用playwright-cli --help可通过终端访问；脚本会自行记录最新的命令和选项，以便你在尝试新操作前能快速回顾。

核心交互循环

1. 首先使用playwright-cli open <url>加载页面（如果需要预先隔离，可添加--session=name参数）。
2. 运行playwright-cli snapshot以生成元素引用（如e1、e2等），此操作需在任何交互前完成。DOM变更或页面跳转后务必重新快照，避免引用失效。
3. 通过引用执行操作：
   • 点击、双击、悬停、拖拽、勾选取消勾选选择填写输入上传执行追加[按钮][值]，或根据需要添加JavaScript代码片段（例如，playwright-cli click e4 right）。
   • 使用截图 [引用]、PDF、控制台 [级别]，或
4. 网络捕获输出证据。,pdf,console [level], ornetwork用于验证流程或检查错误。
5. 示例流程：

   playwright-cli open https://example.com/login
   playwright-cli snapshot
   playwright-cli fill e1 "user@example.com"
   playwright-cli fill e2 "supersecret"
   playwright-cli click e3
   playwright-cli snapshot
   playwright-cli screenshot
   

会话与持久性

• 使用--session=<名称>来保持每个工作流程中的cookie、存储和标签页隔离。会话的行为类似于持久化配置文件：它们能记住命令之间的认证状态、历史记录和标签页。
• 导出PLAYWRIGHT_CLI_SESSION=我的会话如果您在同一会话中运行多个命令——CLI将默认使用该会话，无需每次指定--session。
• 显式管理会话：

  playwright-cli session-list
  playwright-cli session-stop <name>
  playwright-cli session-stop-all
  playwright-cli session-restart <name>
  playwright-cli session-delete <name>
  

• 使用playwright-cli --isolated open ...来创建不持久化到磁盘的临时上下文。
• 每当您更改会话的浏览器设置（启动参数、无头模式切换、浏览器选择）时，请重新运行playwright-cli config以更新该会话的配置，然后运行session-restart以应用新配置。

标签页、导航与开发者工具

• 标签页辅助功能：tab-list、tab-new [url]、tab-close <index>、tab-select <index>。
• 导航快捷键：go-back、go-forward、reload。
• 键盘与鼠标控制：press <key>、keydown、keyup、mousemove <x> <y>、mousedown [button]鼠标抬起 [按钮]鼠标滚轮 <dx> <dy>.开发者工具式内省：使用这些功能来检查控制台日志、检查网络请求或注入辅助脚本。
• 录制、跟踪与导出

  playwright-cli console [level]
  playwright-cli network
  playwright-cli run-code "async page => await page.context().grantPermissions(['clipboard-read'])"
  

  围绕精细交互录制跟踪记录和视频，以便稍后回放代理的操作：

使用

• 截图

  playwright-cli tracing-start
  # perform steps
  playwright-cli tracing-stop
  playwright-cli video-start
  # perform steps
  playwright-cli video-stop video.webm
  

• 、PDF或快照（会转储元素引用）将证据保存到磁盘。录制的文件遵循配置中的输出目录设置。配置、状态与维护使用

playwright-cli 配置

• 来调整运行时标志而无需重新安装。例如：更改to tweak runtime flags without reinstalling. Examples:

  playwright-cli config --headed --browser=firefox
  playwright-cli --session=auth config --config=playwright-cli.json
  

  Change浏览器，上下文选项、启动选项，或配置中的录制设置，并重启会话以应用它们。
• 运行playwright-cli install会在环境是新的或您收到缺少二进制文件的错误时刷新浏览器二进制文件。
• 完成后清理会话以避免状态陈旧：

  playwright-cli session-stop <name>
  playwright-cli session-delete <name>
  

故障排除与提醒

• 如果命令失败，请重新运行playwright-cli snapshot以确认引用仍然有效。快照为点击/输入操作提供当前的DOM上下文。
• playwright-cli --help总是显示最新的命令集，因此在尝试使用不常用的标志前请查阅它。
• 当代理需要复制一个已记录的手动流程时，捕获屏幕截图，记录会话名称，并说明使用了哪些引用和标签页。
• 如果需要针对可见浏览器（例如，手动检查），请使用--headed重新配置，或仅针对该会话运行playwright-cli open --headed <url>。