SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场playwright

playwright

测试与质量

查看项目

更新于 10-15 18:31

技能介绍

Playwright CLI Skill 是一个以命令行界面（CLI）为优先方式的浏览器自动化技能，目标是在终端中驱动真实浏览器完成自动化操作。

用途 该技能适用于需要从终端自动化真实浏览器的任务，包括导航、表单填写、快照、截图、数据提取和 UI 流程调试等。它被定位为 CLI 优先的自动化工具，不转向 @playwright/test，除非用户明确要求生成测试文件。

主要能力

  • 通过 playwright-cli 在终端驱动浏览器。
  • 打开页面（支持 --headed 有头模式以便进行视觉检查）。
  • 获取快照（snapshot）以获得稳定的元素引用。
  • 使用快照中的引用进行交互，如 click、type、press、fill 等。
  • 捕获产物，包括截图、pdf、追踪（traces）。
  • 表单填写与提交。
  • 使用追踪（tracing-start / tracing-stop）调试 UI 流程。
  • 多标签页操作（tab-new、tab-list、tab-select）。

使用方式 前置检查（必需）：在提出命令之前，检查 npx 是否可用，因为包装脚本依赖它：

command -v npx >/dev/null 2>&1

如果 npx 不可用，暂停并请用户安装 Node.js/npm（它提供 npx）。提供以下步骤（原文照录）：

Verify Node/npm are installed

node --version npm --version

If missing, install Node.js/npm, then:

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

一旦 npx 就绪，使用包装脚本继续进行。playwright-cli 的全局安装是可选的。

技能路径（设置一次）：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}" export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"

用户级技能安装在 $CODEX_HOME/skills 下（默认：~/.codex/skills）。

快速开始（使用包装脚本）：

"$PWCLI" open https://playwright.dev --headed "$PWCLI" snapshot "$PWCLI" click e15 "$PWCLI" type "Playwright" "$PWCLI" press Enter "$PWCLI" screenshot

如果用户偏好全局安装，以下方式同样有效：

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

核心工作流

  1. 打开页面。
  2. 获取快照以得到稳定的元素引用。
  3. 使用最新快照中的引用进行交互。
  4. 在导航或 DOM 发生显著变化后重新快照。
  5. 在有用时捕获产物（截图、pdf、追踪）。

最小循环示例：

"$PWCLI" open https://example.com "$PWCLI" snapshot "$PWCLI" click e3 "$PWCLI" snapshot

何时需要重新快照 在以下情况后再次快照：

  • 导航
  • 点击会显著改变 UI 的元素
  • 打开/关闭模态框或菜单
  • 切换标签页 引用可能会失效。当命令因引用缺失而失败时，重新快照。

推荐模式 表单填写与提交：

"$PWCLI" open https://example.com/form "$PWCLI" snapshot "$PWCLI" fill e1 "user@example.com" "$PWCLI" fill e2 "password123" "$PWCLI" click e3 "$PWCLI" snapshot

使用追踪调试 UI 流程：

"$PWCLI" open https://example.com --headed "$PWCLI" tracing-start

...interactions...

"$PWCLI" tracing-stop

多标签页工作：

"$PWCLI" tab-new https://example.com "$PWCLI" tab-list "$PWCLI" tab-select 0 "$PWCLI" snapshot

包装脚本 包装脚本使用 npx --package @playwright/cli playwright-cli，使 CLI 无需全局安装即可运行：

"$PWCLI" --help

除非仓库已统一采用全局安装，否则优先使用包装脚本。

参考资料 按需打开：

  • CLI 命令参考：references/cli.md
  • 实用工作流与故障排除：references/workflows.md

护栏（Guardrails）

  • 在引用像 e12 这样的元素 id 之前，始终先做快照。
  • 当引用看起来失效时，重新快照。
  • 优先使用显式命令，而不是 eval 和 run-code，除非确有需要。
  • 当没有最新快照时，使用像 eX 这样的占位引用并说明原因；不要用 run-code 绕过引用。
  • 当视觉检查有帮助时，使用 --headed。
  • 在本仓库中捕获产物时，使用 output/playwright/，避免引入新的顶层产物文件夹。
  • 默认使用 CLI 命令和工作流，而不是 Playwright 测试规范。

适用场景

  • 终端驱动的浏览器会话自动化。
  • 表单填写与提交。
  • UI 流程调试（结合追踪）。
  • 多标签页操作。
  • 页面快照、截图、数据提取。

限制

  • 需要 npx 可用（依赖 Node.js/npm），否则需先安装。
  • 默认面向 CLI 工作流，不生成 @playwright/test 测试文件，除非用户明确要求。
  • 交互依赖快照产生的元素引用，引用可能失效，需要重新快照。
  • 更多官方说明、收费与价格等信息暂未提供。