playwright

playwright skill 概览

这个 skill 的作用

playwright skill 用于通过终端借助 playwright-cli 驱动真实浏览器，尤其适合需要导航、填写表单、截图、snapshot、内容提取或 UI 流程调试的场景。它面向的是浏览器自动化，而不是编写测试套件；并且它偏向 CLI-first 的工作流，带有一个包装脚本，即使没有全局安装 Playwright 也能运行。

适合安装给谁

如果你希望在不手写完整自动化栈的前提下，稳定控制浏览器，就应该安装 playwright skill。它很适合需要查看在线页面、复现用户流程、收集页面内容，或以可重复的方式排查界面行为的 agent。

最关键的区别

它最核心的差异在于基于 wrapper 的工作流：先检查 npx，再一次性设置 skill 路径，之后通过 PWCLI 调用 playwright-cli 命令。这降低了配置摩擦，也让这个 skill 很适合临时自动化任务，尤其是在浏览器任务比较杂乱、或者 UI 经常变化的时候。

如何使用 playwright skill

安装并设置 skill 路径

先走标准的 skill 安装流程：

npx skills add openai/skills --skill playwright

然后在当前 shell 会话或 profile 里一次性设置路径：

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

在做任何事情之前，先确认 npx 是否存在。如果没有，请先安装 Node.js/npm；这个 wrapper 依赖它。

把一个模糊目标变成好提示词

给这个 skill 的应该是一个具体的浏览器任务，而不是含糊的请求。更好的输入会同时说明站点、目标动作，以及你想要的产物。

好的提示词示例：

• “Use playwright skill to log into the staging app, navigate to the invoices page, and capture a screenshot of the filtered table.”
• “Use playwright for Browser Automation to open this URL, extract the visible product names, and report any console warnings.”
• “Use playwright skill to reproduce this signup error and capture a trace plus the final page state.”

这样可以帮助 skill 选择合适的命令、snapshot 和调试步骤。

先读这些文件

实际使用时，建议先从这些文件开始：

• SKILL.md：核心工作流和约束
• references/cli.md：命令覆盖范围
• references/workflows.md：交互模式和 session 使用方式
• scripts/playwright_cli.sh：了解 wrapper 如何解析 npx

如果你是在判断这个 skill 是否适合你的环境，也可以顺手看一下 agents/openai.yaml 里的默认意图，以及 NOTICE.txt 里的来源信息。

实用工作流建议

使用标准循环：打开页面，snapshot，基于元素 ID 执行动作，然后再 snapshot 一次确认状态变化。做表单时，如果已经知道字段位置，优先用 fill，不要逐个字符敲。调试时，围绕故障点采集 console、network，并在失败前后使用 tracing-start/tracing-stop，不要靠猜。

playwright skill 常见问题

playwright 只是一个提示词，还是一个真正可安装的工作流？

它是一个真正可安装的 playwright skill，包含 wrapper 脚本和参考命令，不只是提示词文本。区别就在于：安装之后你会得到可重复的命令结构、session 处理方式，以及一个可预测的入口点。

什么情况下不该用 playwright？

如果你只需要静态代码生成、普通 HTTP 请求，或者测试运行器，就不该用它。另一种不适合的情况是你的环境无法提供 npx，因为在 Node.js/npm 可用之前，这个 wrapper 会停住。

这个 skill 适合新手吗？

如果你的任务本质上是浏览器任务，而且你能清楚描述页面和目标，那么答案是适合。真正的学习曲线不在 Playwright 语法，而在于如何提出一个足够具体的浏览器结果，并在执行前先检查 snapshot。

它和 @playwright/test 有什么不同？

当你想要的是 CLI 驱动的浏览器自动化时，用这个 skill。只有在你明确需要测试文件、断言，或者测试框架时，才用 @playwright/test。这个 skill 更适合交互式使用和真实业务流程，不是为了完整测试项目而优化的。

如何改进 playwright skill

提供更好的初始状态

最好的输出来自信息完整的输入：把 URL、登录状态、设备或 viewport 约束，以及你希望拿回来的产物都说明白。如果任务涉及认证，请说明凭据是否已经存在、是否预期会有 MFA，以及 skill 是应该在导航后停止，还是继续提交流程。

说清楚成功标准

把结束条件写具体：“在弹窗关闭后保存截图”、“提取前 20 行可见数据”、“点击 Checkout 后报告所有 console 错误”。这样可以减少无谓探索，让 playwright 的执行更可预测。

请求正确的调试产物

如果工作流失败了，就明确要求你需要的证据：用 snapshot 看结构，用截图看视觉状态，用 trace 看交互时序，用 console/network 输出看运行时失败。它们比泛泛地要求“修复问题”的运行结果有用得多。

避免常见失败模式

最常见的错误是对 UI 路径说得太少，却把实现细节说得太死。不要在页面很可能变化的情况下，强行要求精确点击次数；应该直接描述目标，让 skill 根据当前页面状态去导航。也不要把浏览器自动化和测试套件需求混在一起，除非你确实需要 @playwright/test。