名称： playwriter
描述： 通过 Playwriter（remorses）使用持久化 Chrome 会话和完整的 Playwright Page API 进行浏览器自动化。
hats: [developer, qa_tester]

Playwriter

概述

使用 Playwriter 在本地 Chrome 会话中运行 Playwright Page 脚本。这可以保留登录状态、Cookie 和扩展程序，非常适合测试 Web 仪表板和需要身份验证的流程。

适用场景

• 验证 Ralph Web 仪表板的 UI
• 无需重新登录即可导航已认证页面
• 测试需要浏览器扩展或保存状态的流程
• 为元素发现捕获无障碍（a11y）快照

前提条件

• 安装 CLI：
  bash npm i -g playwriter
• 安装 Playwriter Chrome 扩展（请参阅 Playwriter 仓库的说明）
• 确保 Chrome 正在运行且扩展已启用

核心工作流

1. 创建会话：
   bash playwriter session new
2. 列出会话并复制会话 ID：
   bash playwriter session list
3. 针对该会话执行 Playwright 代码：
   bash playwriter -s <会话ID> -e "await page.goto('https://example.com')"

执行环境

在 -e 参数内，以下对象在作用域中可用：
- page (Playwright Page)
- context (BrowserContext)
- state (同一会话中跨调用持久存在的对象)
- require (用于加载辅助模块)

状态持久化示例：

playwriter -s <会话ID> -e "state.lastUrl = page.url()"
playwriter -s <会话ID> -e "console.log(state.lastUrl)"

常用模式

导航 + 点击

playwriter -s <会话ID> -e "await page.goto('http://localhost:3000'); await page.getByRole('button', { name: '运行' }).click();"

填写表单

playwriter -s <会话ID> -e "await page.getByLabel('邮箱').fill('qa@example.com'); await page.getByLabel('密码').fill('secret'); await page.getByRole('button', { name: '登录' }).click();"

无障碍快照（带标签）

playwriter -s <会话ID> -e "const { screenshotWithAccessibilityLabels } = require('playwriter'); await screenshotWithAccessibilityLabels(page, { path: '/tmp/a11y.png' });"

网络拦截

playwriter -s <会话ID> -e "await page.route('**/api/**', async route => { const res = await route.fetch(); const body = await res.json(); await route.fulfill({ json: { ...body, injected: true } }); });"

读取页面内容

playwriter -s <会话ID> -e "const text = await page.locator('main').innerText(); console.log(text);"

提示

• 优先使用 getByRole 和 getByLabel 来获取稳定的选择器。
• 使用无障碍快照来发现可靠的角色和标签。
• 保持会话专注：如果状态变得混乱，请重置或关闭会话。
• 对于多步骤流程，将中间数据存储在 state 上。