playwright-skill-v2

Playwright 技能 v2

使用 playwright-cli（Microsoft 官方 Playwright CLI）进行浏览器自动化。无需管理守护进程——浏览器会自动启动和停止。

---

1. 会话启动与隔离

始终使用 bin/open 启动（不要直接使用 playwright-cli open）：

bin/open --headed
playwright-cli goto <url>

bin/open 会根据当前目录生成会话名称（例如 my-project），在 Claude Code 下运行时会附加一个简短的 Agent 标识符，并在该命名会话下启动浏览器。所有其他 bin/ 脚本都会自动解析会话。

会话隔离： 设置 CLAUDE_SESSION_ID 时（在 Claude Code 中会自动设置），每个 Agent 都会获得独立的会话名称（例如 my-project-a1b2c3d4）和会话文件。并行运行的 Agent 互不干扰。如果该 Agent 已有会话处于打开状态，bin/open 会先将其关闭，以防止遗留 Chrome 进程；其他 Agent 的会话不受影响。

打开新会话前，请检查自己是否已有会话：

playwright-cli list    # see all open sessions

如果列表中已有你的会话且处于打开状态，请跳过 bin/open，直接使用该会话。

任务结束时，使用以下命令清理：

bin/close

此操作会关闭浏览器并移除会话跟踪文件。如果浏览器卡住，请改用 playwright-cli kill-all。

覆盖会话名称：

bin/open --headed --session my-custom-name

---

2. 读取快照

每条命令执行后，stdout 都会包含指向当前无障碍树的链接：

### Snapshot
- [Snapshot](.playwright-cli/page-<timestamp>.yml)

始终读取快照文件，查看页面内容：

Read .playwright-cli/page-<timestamp>.yml

快照包含所有交互元素及其 [ref=eN] 标识符，可用于点击、填写和悬停操作。

---

3. 核心命令

导航

playwright-cli goto <url>          # navigate to URL
playwright-cli go-back             # browser back
playwright-cli go-forward          # browser forward
playwright-cli reload              # reload page

导航安全： 仅导航到与项目 baseUrl（在 skill/worktrees.json 中定义）匹配的 URL 及其子路径。除非用户明确要求，否则不要导航到外部或未知域名。这样可防止 Cookie、身份验证令牌等数据意外泄露给第三方网站。

与元素交互（使用快照中的 ref）

playwright-cli click <ref>         # click element
playwright-cli fill <ref> <value>  # fill input (clears first)
playwright-cli type <text>         # type text (appends)
playwright-cli press <key>         # press key: Enter, Tab, Escape, Control+A
playwright-cli hover <ref>         # hover to reveal menus/tooltips
playwright-cli select <ref> <val>  # select dropdown option

观察

playwright-cli snapshot            # capture accessibility tree
playwright-cli screenshot          # take screenshot

对话框

playwright-cli dialog-accept       # accept alert/confirm/prompt
playwright-cli dialog-dismiss      # dismiss dialog

会话管理

bin/close                          # close browser session + clean up session file (preferred)
playwright-cli kill-all            # force-kill all playwright-cli daemons (use when stuck)
playwright-cli list                # list all open sessions

应急方案

playwright-cli run-code '<async page => { }>'   # run arbitrary Playwright JS

---

4. CSS 选择器回退方案

ARIA-ref 命令失败时使用这些方案，例如框架渲染的元素位于主 ARIA 树之外时。

模态对话框——通常以 DOM portal 的形式渲染：

bin/click-css "[data-modal-confirm]"
bin/click-css "button[data-dismiss]"

隐藏的文件输入框——通常在无障碍树中不可见：

bin/upload "input[type=file]" /path/to/file.pdf

框架事件目标——ARIA-ref 点击不一定会触发框架事件处理程序：

bin/fill-css "[data-field=email]" "[email protected]"
bin/click-css "[data-action=save]"

项目专用的选择器模式请参阅 skill/CONFIG.md。

---

5. 身份验证配置

身份验证配置名称和基础 URL 定义在 skill/worktrees.json 中（已加入 gitignore）。 设置说明请参阅 skill/CONFIG.md。

完成身份验证后保存：

bin/auth-save <profile-name>          # profile names from skill/worktrees.json

在新会话中恢复：

bin/open --headed
playwright-cli goto <baseUrl>          # baseUrl from skill/worktrees.json
bin/auth-load <profile-name>
playwright-cli goto <baseUrl>/dashboard

配置存储在 .playwright-skill/auth/ 中，且已加入 gitignore。

---

6. 故障恢复

问题	解决方案
浏览器卡住／守护进程挂起	执行 playwright-cli kill-all，然后执行 bin/open --headed
会话未打开（bin/context 错误）	执行 bin/open --headed
身份验证已过期	执行 bin/auth-load <profile>，然后重新加载
未找到元素 ref	执行 playwright-cli snapshot，然后读取新的快照文件
无法点击 Filament 模态框	使用带 CSS 选择器的 bin/click-css
任务结束时清理	执行 bin/close

---

7. run-code 示例

# Wait for a specific element
playwright-cli run-code 'await page.waitForSelector(".loading-complete")'

# Dispatch a Livewire event
playwright-cli run-code 'await page.evaluate(() => window.Livewire.dispatch("refresh"))'

# Scroll to bottom
playwright-cli run-code 'await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))'

# Get element count
playwright-cli run-code 'console.log(await page.locator("table tbody tr").count())'

---

8. 上下文捕获与 QA 工作流

三个工具将 ResponseBuilder 和 CacheStore 集成到 v2 技能中，可提供丰富的页面诊断信息。

工具

命令	描述
bin/context [--screenshot]	捕获完整页面上下文 → 在 stdout 输出精简的 TrimmedResponse JSON
bin/inject-capture	注入浏览器端控制台及 fetch/XHR 补丁
bin/cache-query <cmd> [args]	按 ID 和类型查询缓存数据

bin/context

从三个来源收集上下文，并将其存储在 .playwright-skill/cache/ 中：

1. playwright-cli snapshot — 无障碍树（YAML）
2. playwright-cli console / playwright-cli network — 浏览器原生日志
3. playwright-cli run-code — 页面 URL、标题、HTML、Cookie、注入的捕获数据

输出一个 TrimmedResponse（约 200 个 token），其中包含：

• pageState — URL、标题、身份验证状态、错误标记
• cacheRef.id — 用于稍后检索完整上下文的引用 ID
• cacheRef.available — 可用数据类型列表

bin/context             # text/ARIA capture only
bin/context --screenshot  # also capture PNG screenshot

bin/inject-capture

在浏览器中修补 console.*、window.fetch 和 XMLHttpRequest，以便在 window.__capturedConsole 和 window.__capturedRequests 中捕获事件。bin/context 会将这些数据与 Playwright 层捕获的数据合并。

幂等——可安全地多次运行。只捕获注入之后发生的事件。

bin/inject-capture
# → {"success":true,"hasCapture":true}

bin/cache-query

检索由 bin/context 存储的完整上下文。

bin/cache-query query <id> snapshot    # accessibility tree YAML
bin/cache-query query <id> html        # full page HTML
bin/cache-query query <id> console     # console messages JSON
bin/cache-query query <id> network     # network requests JSON
bin/cache-query query <id> screenshot  # base64-encoded PNG
bin/cache-query list                   # JSON array of all cached entries
bin/cache-query stats                  # entry count, total size, max entries
bin/cache-query clear                  # clear all entries
bin/cache-query clear <id>             # clear one entry

典型 QA 工作流

# 1. Start browser and navigate
bin/open --headed
playwright-cli goto http://localhost:8000
bin/auth-load <profile>

# 2. Inject browser-side capture (optional but recommended)
bin/inject-capture

# 3. Perform actions (click, fill, navigate...)
playwright-cli click e5
playwright-cli fill e7 "search term"
playwright-cli press Enter

# 4. Capture full context
bin/context --screenshot
# Read cacheRef.id from the TrimmedResponse output

# 5. Diagnose issues
bin/cache-query query <id> console     # check for JS errors
bin/cache-query query <id> network     # check API responses
bin/cache-query query <id> snapshot    # review page structure
bin/cache-query query <id> screenshot  # view page visually (base64 PNG)

# 6. Clean up
bin/close

多项目 / 并行 Agent 注意事项： 在 Claude Code 下运行时，每个 Agent 都会通过 CLAUDE_SESSION_ID 自动获得隔离会话。仅打开一个会话时，直接运行 playwright-cli 命令（goto、click、fill 等）即可。如果有多个会话处于活动状态，请添加 -s=<session> 前缀，例如：playwright-cli -s=my-project-a1b2c3d4 goto <url>。运行 bin/open 时会打印会话名称。

阅读控制台错误

bin/cache-query query <id> console | python3 -c "
import sys, json
msgs = json.load(sys.stdin)
errors = [m for m in msgs if m['type'] == 'error']
for e in errors:
    print(e['text'])
"