playwright

name	playwright
description	当任务需要通过 `playwright-cli` 或随附的封装脚本从终端自动化操作真实浏览器时使用（导航、填表、快照、截图、数据提取、UI 流程调试）。

Playwright CLI 技能

用 playwright-cli 从终端驱动真实浏览器。优先使用随附的封装脚本，这样即使 CLI 没有全局安装也能工作。 把本技能当作 CLI 优先的自动化。除非用户明确要求测试文件，否则不要转向 @playwright/test。

前置检查（必需）

在建议命令之前，先检查 npx 是否可用（封装脚本依赖它）：

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

如果不可用，暂停并请用户安装 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 PWCLI="<skill-root>/playwright/scripts/playwright_cli.sh"

用户级技能安装在 <skill-root> 下（默认：<skill-root>）。

快速开始

使用封装脚本：

"$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、trace）。

最小循环：

"$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 at example dot com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

用 trace 调试 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

护栏

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