Playwright 1.59：代理测试 API — 指南

Playwright 1.59：代理式测试成为标准——关键 API 详解

Playwright 1.59 版本的发布标志着从手动测试设置向代理式工作流的转变。新推出的可视化工具、共享会话访问以及 CLI 集成，弥合了 AI 生成测试与其实际应用之间的差距。让我们来剖析技术领导者如何将这些功能集成到现有管道中。

屏幕录制 API：从截图到视觉证明

新的 page.screencast API 用完整的视频记录取代了测试失败时的碎片化截图。其关键区别在于内置的操作标注和章节，用于组织长场景。这不仅仅是屏幕录制——而是一份上下文化的执行报告。

关键端到端流程的使用示例：

await page.screencast.start({ path: 'checkout.webm' });
await page.screencast.showActions({ position: 'top-right' });
await page.locator('#add-to-cart').click();
await page.locator('#checkout').click();
await expect(page.locator('.order-confirmation')).toBeVisible();
await page.screencast.stop();

与 AI 视觉模型集成时，onFrame 回调可将帧数据输入视觉模型：

await page.screencast.start({
  onFrame: ({ data }) => sendToVisionModel(data),
  size: { width: 800, height: 600 },
});

这解决了无需像素级比较的视觉验证问题。对于 CI 环境，建议添加描述各阶段的章节：

await page.screencast.showChapter('Authentication', {
  description: 'Test login process',
  duration: 1000,
});
// login steps
await page.screencast.showChapter('Payment', {
  description: 'Credit card validation',
});

带章节的视频可以将失败分析速度提升 3-4 倍，相比纯文本日志。

浏览器绑定 API：跨工具同步

browser.bind() 功能创建 WebSocket 连接，实现对单一浏览器会话的共享访问。这消除了在手动测试与自动化切换时的重复认证。

基本场景：

const { endpoint } = await browser.bind('auth-session', {
  workspaceDir: '/project',
});

CLI 连接：

playwright-cli attach auth-session
playwright-cli -s auth-session snapshot

实际用例：

• 实时调试 AI 代理，而不中断流程
• 在 QA 和开发者之间共享已认证会话
• 与 MCP 服务器集成，用于混合工作流（例如，代理生成测试，团队进行调整）

对于使用自愈测试的团队至关重要：代理可以通过绑定会话检查变更来修复场景。

仪表板和 CLI 工具：无 GUI 调试

playwright-cli show 命令启动仪表板，提供所有绑定会话的实时监控。对于代理式工作流，新增两种关键模式：

• CLI 调试器 (--debug=cli)：通过终端进行逐步调试

```

npx playwright test --debug=cli

playwright-cli --session tw-87b59e step-over

```

允许代理在无 GUI 情况下分析失败，并在每步检查 DOM。

• Trace 分析 (npx playwright trace)：程序化跟踪解析

- 提取网络请求和时间戳

- 自动生成精确定位失败时刻的 bug 报告

- 与分析系统集成（例如，Grafana）

这些工具对于传统调试方法不可用的无头 CI 环境至关重要。

技术领导者的关键要点

• 视觉记录取代日志：带操作标注的 30 秒视频可将诊断速度提升 4 倍
• 共享会话节省时间：消除重新认证可将测试管道开销降低 15-20%
• CLI 优先方法：终端集成使代理式工作流在生产环境中可行
• 直接 AI 集成：将帧数据输入视觉模型，并通过自愈代理自动生成修复
• 利益相关者透明度：视频报告将技术细节转化为清晰证明

如何集成到现有流程

团队入门策略：

• 从屏幕录制 API 开始，针对关键场景（订单结账、支付）。为关键阶段添加章节——这能立即带来诊断收益。

• 设置浏览器绑定 用于共享会话：

```

# 在设置脚本中

await browser.bind('auth-state', { storageState: 'state.json' });

```

从终端连接进行手动检查，无需重新登录。

• 通过 CI 中的 PLAYWRIGHT_DASHBOARD=1 启用仪表板。这提供并行运行的可视化监督。

• 将 CLI 调试器集成到自愈管道：

```

# 在自愈代理脚本中

if (testFailed) {

await runCLI(playwright-cli attach ${session} fix);

}

```

升级到 1.59 版本只需最少的代码变更，但会转变测试范式：QA 工程师不再是“测试编写者”，而是代理式解决方案的验证者。 rollout 屏幕录制 API 后一周内即可看到初步效果——团队将注意到失败分析时间显著缩短。

— Editorial Team