技能使用指南

playwright（PlaywrightCLI技能Skill）Skill 是什么？命令行浏览器自动化好用吗？

一文看懂 playwright（PlaywrightCLI技能Skill）：用命令行驱动真实浏览器，完成打开页面、快照取元素、点击填表、截图取证与流程跟踪，包装脚本免全局安装。内含安装步骤、完整命令示例、竞品对比与典型场景，帮前端、QA 与运营快速上手浏览器自动化。

PlaywrightCLI技能Skill"playwright"
8 个章节 约 16 分钟阅读 AI 智能生成

PlaywrightCLI技能Skill：用命令行驱动真实浏览器，把网页自动化压缩成几条命令

  • 一句话定位：这是一个「CLI 优先」的浏览器自动化技能，让你在命令行里完成打开网页、快照取元素、点击填表、截图取证、跟踪调试等真实浏览器操作。
  • 核心机制：先用 snapshot 拿到稳定的元素引用（如 e15、e3），再用引用去点击、输入、按键，DOM 变化后重新快照，形成「打开 → 快照 → 交互 → 再快照」的最小闭环。
  • 安装友好：技能自带包装脚本，通过 npx --package @playwright/cli playwright-cli 运行，即使没有全局安装 CLI 也能用；全局安装只是可选项。
  • 不是测试框架：技能明确要求，除非用户主动要求测试文件，否则不要转向 @playwright/test，它面向的是「临时自动化真实浏览器」而不是「写测试规范」。
  • 适合谁用：需要复现 UI 缺陷的前端/QA、要抓取页面数据或截图取证的运营与数据同学、以及想用对话方式调试网页流程的开发者。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能中文名：PlaywrightCLI技能Skill 技能英文名：playwright 技能ID：12163

它解决的问题很具体：很多任务需要「真的打开一个浏览器点一下」，比如验证某个按钮点了会不会报错、帮运营把表单填完截图、把页面数据抓下来、或者复现用户描述的 UI 异常。传统做法是写一段 Playwright/Puppeteer 脚本，或者装一堆浏览器插件手动点。这个技能把这件事变成了「一句话 + 几条 CLI 命令」：AI 直接调用 playwright-cli 驱动真实浏览器，你只需要看结果。

「一键安装」的思路是：技能装一次 + 环境变量设一次 + 一条命令验证，之后所有浏览器任务都复用这套环境。

第 1 步：安装前提检查（技能要求必须先做）

包装脚本依赖 npx，所以在提出任何命令之前，先确认它存在：

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

如果没有输出（说明不可用），技能会暂停并提示你先安装 Node.js/npm，因为它提供 npx。验证方式：

node --version
npm --version

如果缺失，先装 Node.js/npm，然后再考虑可选的全局安装：

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

第 2 步：设置技能路径（只需设置一次）

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

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

第 3 步：验证是否生效

"$PWCLI" --help

能看到命令帮助，说明包装脚本与 CLI 都正常。之后就可以跑最小闭环验证：

"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot

第 4 步：选择运行模式

  • 默认推荐用包装脚本（"$PWCLI" ...），免全局安装、随技能走；
  • 如果所在团队/仓库已经统一用全局安装，也可以直接用 playwright-cli 命令，两种方式都支持。
  • 具体安装包版本、技能市场入口、平台价格等信息以官方说明为准。

该技能的主要功能和特点

  • CLI 优先的真实浏览器自动化：导航、表单填写、快照、截图、数据提取、UI 流程调试，全部通过命令行完成，不依赖图形界面操作。
  • 快照取引用，交互更稳：snapshot 会返回稳定的元素引用（如 e15），后续 click e15、fill e1 "..." 都基于引用，比按坐标点击或脆弱选择器可靠。
  • 免全局安装的包装脚本：包装脚本内部使用 npx --package @playwright/cli playwright-cli，没装全局 CLI 也能跑，这是它在门槛上最明显的优势。
  • 常见的交互命令集：open（打开页面）、snapshot（快照）、click（点击）、type（输入）、fill（填表）、press（按键，如 Enter）、screenshot（截图）。
  • 多标签页管理：tab-new 新建标签、tab-list 列出标签、tab-select 0 切换标签，再做快照，适合对比页或多窗口流程。
  • 跟踪调试：tracing-start / tracing-stop 记录整个交互过程，配合 --headed 可视化观察，定位 UI 流程问题很直观。
  • 工件捕获：截图、PDF、跟踪等产物可以落盘，技能约定在本仓库中使用 output/playwright/，避免到处新建顶级工件文件夹。
  • 明确的护栏设计：引用 e12 之前必须先快照；引用似乎过时就要重新快照；优先用显式命令而不是 eval / run-code 绕过；没有新快照时用 eX 占位并说明原因。这套约束让它比「随手写段脚本」更可控。
  • 按需查阅参考资料：需要命令细节看 references/cli.md，需要实用工作流与故障排除看 references/workflows.md，不用一次性加载全部内容。

和「普通工具」相比强在哪？强在入口统一（都是命令行，AI 可直接调用）、元素定位稳定（快照引用而非坐标）、过程可回放（跟踪文件）、安装门槛低（包装脚本免全局安装），并且它是给 AI 用的「CLI 优先」模式，而不是让你先学一套测试框架。

如何使用该技能？

下面是分步骤的使用指南，命令均来自技能说明，可直接参考。

步骤 1：确认前提条件

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

无输出就先装 Node.js/npm，再继续。

步骤 2：设置一次环境变量

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

步骤 3：打开页面

"$PWCLI" open https://example.com

需要肉眼看过程时加 --headed：

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

步骤 4：快照，拿到元素引用

"$PWCLI" snapshot

输出会给出一批元素引用（形如 e1、e3、e15），这些就是后续操作的「把手」。

步骤 5：用引用执行交互

"$PWCLI" click e3
"$PWCLI" type "Playwright"
"$PWCLI" press Enter

如果是表单，用 fill 更直接：

"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3

步骤 6：DOM 变化后重新快照

导航、点击导致 UI 显著变化、打开/关闭模态框或菜单、切换标签页之后，都要重新快照，因为旧引用可能失效：

"$PWCLI" snapshot

步骤 7：取证与记录

"$PWCLI" screenshot
"$PWCLI" tracing-start
# ...继续交互...
"$PWCLI" tracing-stop

步骤 8：多标签页场景

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

输入与输出说明：输入是命令 + 目标 URL + 快照返回的元素引用；输出是页面状态变化、快照文本（含引用清单）、截图/跟踪等工件。最小循环就是四行：

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

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
PlaywrightCLI技能Skill（playwright） 给 AI 用的 CLI 优先浏览器自动化技能 导航、快照、点击/填表/按键、截图、跟踪、多标签页 需 npx（Node.js/npm）；包装脚本免全局安装 临时自动化、复现 UI 问题、抓页面信息、填表取证 优势：入口统一、快照引用稳定、免全局安装、有护栏约束；不足：需要理解「快照→引用」的心智模型，不产出测试代码
@playwright/test 测试框架 正式端到端测试工程 测试规范、断言、断言报告、CI 集成 需搭建项目结构与依赖 回归测试、CI 流水线 优势：工程化、可长期维护；不足：为写测试文件而设计，临时脚本类任务偏重，本技能也明确不建议默认转向它
通用浏览器自动化脚本（如 Puppeteer / Selenium 手写脚本） 代码级浏览器驱动 几乎全部浏览器操作 需自己写代码、维护选择器与等待逻辑 定制化爬虫、复杂流程 优势：灵活；不足：选择器易碎、脚本要自己维护，缺少「快照引用 + 跟踪」的开箱能力
纯手工浏览器操作 人工点击 一切视觉可见操作 零门槛 简单一次性操作 优势：无学习成本；不足：不可复现、不可批量、难以留下可追溯的工件与跟踪

从对比看，这个技能的差异化位置很清楚：它既不是重型测试框架，也不是从零写脚本，而是把「真实浏览器操作」变成一组可被 AI 直接调度、可回放、可证据化的命令。

该技能的典型应用场景与实际体验情况

场景一：前端/QA 复现用户反馈的 UI 缺陷

痛点：用户说「点提交之后弹窗关不掉」，但开发本地复现不出来。 使用方式：open 目标页并加 --headed，snapshot 后在真实界面上按用户路径点一遍，tracing-start/tracing-stop 把整个过程录下来，最后 screenshot 留证。 实际体验：上手很快，关键是每一步操作前先快照；--headed 让「到底点到了哪个元素」一目了然，跟踪文件比口头描述有说服力得多。注意模态框开合后一定要重新快照，否则会点到旧引用。

场景二：运营/数据同学填表与信息提取

痛点：需要把几十条信息填进后台表单，或把页面上的结构化信息抄下来。 使用方式：open 表单页 → snapshot → fill e1 "user@example.com"、fill e2 "password123" → click e3 → 再 snapshot 确认结果。 实际体验：fill 比模拟逐字输入更省事，snapshot 输出本身就是一份可读的页面结构，取数据时不必自己写选择器。注意不要在没快照的情况下凭猜测写 e1、e2，引用是快照里给的，不是自己编的。

场景三：多人协作前的页面核对

痛点：需要在两个页面之间来回比对文案或状态。 使用方式：tab-new 开第二个标签，tab-list 看清单，tab-select 0 切回，再 snapshot 对比。 实际体验：多标签切换命令很轻，切完记得重新快照即可。这个场景里最容易犯的错是切换标签后复用旧引用，命令会因为找不到引用而失败——按技能护栏重新快照就能恢复。

场景四：调试需要「看得见」的交互流程

痛点：某些流程逻辑在无头模式下说不清，需要人工观察。 使用方式：全程带 --headed 跑一遍，必要时用 tracing-start/tracing-stop 记录，把截图和跟踪放到 output/playwright/。 实际体验：可视化 + 跟踪的组合对定位问题帮助最大；注意技能偏好显式命令而非 eval/run-code，别为了省事绕过引用机制，否则问题会更难查。

该技能能为用户带来的价值

  • 把「装环境」变成「一次性配置」：检查 npx → 设置两个环境变量 → --help 验证，三步之后浏览器任务随时可用；包装脚本免全局安装，团队里不必人人 npm install -g。
  • 把「写脚本」压缩成「几条命令」：最小闭环只有 open / snapshot / click / snapshot 四行，临时任务的启动成本从「建工程、写选择器、处理等待」降到「打开、快照、点一下」。
  • 把「说不清」变成「看得见」：截图 + 跟踪文件让 UI 问题有可复现的证据链，减少开发与 QA、用户之间的来回扯皮。
  • 降低非工程角色的门槛：运营、数据、产品不必维护代码仓库，也能完成填表、取数、页面核对这类真实浏览器操作。
  • 行为可控、结果可信：先快照再用引用、过期就重新快照、优先显式命令，这套护栏显著减少了「点了但点错」的隐性错误；工件统一落在 output/playwright/，仓库也不会被临时文件搞乱。
  • 长期价值：同一套命令与工作流可反复复用，命令细节查 references/cli.md、故障排查查 references/workflows.md，团队沉淀一份操作习惯即可长期受益。

常见问题 FAQ

Q1：这个技能怎么安装？必须先全局装 playwright-cli 吗？ 不必须。技能推荐使用捆绑的包装脚本，内部通过 npx --package @playwright/cli playwright-cli 运行，因此即使没全局安装也能用。前提是 npx 可用（即装过 Node.js/npm），技能也要求执行前先用 command -v npx >/dev/null 2>&1 检查。全局安装（npm install -g @playwright/cli@latest）只在仓库已统一标准化时才推荐。具体版本与入口以官方说明为准。

Q2：我让它帮我写自动化测试文件，它却只给命令，是没生效吗？ 不是。这个技能的定位是「CLI 优先的自动化」，明确说明除非用户主动要求测试文件，否则不要转向 @playwright/test。如果你确实想要测试工程，请直接说「我要测试文件」，明确表达需求即可。

Q3：为什么命令报错说找不到引用 e12？ 大概率是引用过期了。技能护栏要求：点击导致 UI 显著变化、导航、打开/关闭模态框、切换标签页之后都要重新 snapshot。解决办法就是重新快照，从新输出里取引用。没有新鲜快照时，应按规范用 eX 这类占位符并说明原因，而不是用 run-code 绕过引用机制。

Q4：收费吗？需要额外买服务吗？ 脚本内容本身不涉及付费说明；它依赖的 Node.js/npm、@playwright/cli 包的许可与费用情况请以各自官方说明为准，本技能没有提供价格信息。

Q5：这个技能适合谁用？和 Playwright 测试框架怎么选？ 适合需要「临时、真实、可取证」地操作浏览器的场景：复现 UI 缺陷、填表提交、页面数据提取、多标签页核对、带可视化与跟踪的流程调试。如果你要的是可长期维护、跑在 CI 里的回归测试，就用 @playwright/test；如果只是一次性任务或让 AI 直接动手，优先用本技能的 CLI 命令模式。