名称: dyad:debug-with-playwright 描述: 通过在关键点截图来视觉检查应用状态以调试 E2E 测试。

使用 Playwright 截图调试

通过在关键点截图来视觉检查应用状态以调试 E2E 测试。

参数

$ARGUMENTS: （可选）指定要调试的 E2E 测试文件（例如，main.spec.ts 或 e2e-tests/main.spec.ts）。如果未提供，将询问用户要调试哪个测试。

背景

Dyad 使用 Electron + Playwright 进行 E2E 测试。因为 Playwright 内置的 screenshot: "on" 选项不适用于 Electron（见 https://github.com/microsoft/playwright/issues/8208），必须通过 page.screenshot() 手动截图。

e2e-tests/helpers/fixtures.ts 中的测试夹具已经在测试失败时自动捕获截图并附加到测试报告中。但对于调试，通常需要在测试执行过程中的特定点截图。

说明

识别要调试的测试:

如果 $ARGUMENTS 为空，询问用户要调试哪个测试文件。
- 如果提供时没有 e2e-tests/ 前缀，添加它
- 如果提供时没有 .spec.ts 后缀，添加它
读取测试文件:

读取测试文件以了解其功能和可能失败的地方。

向测试添加调试截图:

在测试的关键点添加 page.screenshot() 调用来捕获视觉状态。从 po 夹具访问页面：

// 从 electronApp 夹具获取页面
const page = await electronApp.firstWindow();

// 或者如果只有 `po`，直接访问页面：
// po 是一个 PageObject，它有 `page` 属性

调试截图模式:

import * as fs from "fs";
import * as path from "path";

// 创建调试截图目录
const debugDir = path.join(__dirname, "debug-screenshots");
if (!fs.existsSync(debugDir)) {
  fs.mkdirSync(debugDir, { recursive: true });
}

// 拍摄全页面截图
await page.screenshot({
  path: path.join(debugDir, "01-before-action.png"),
});

// 拍摄特定元素的截图
const element = page.locator('[data-testid="chat-input"]');
await element.screenshot({
  path: path.join(debugDir, "02-chat-input.png"),
});

// 在某个操作后截图
await po.sendPrompt("hi");
await page.screenshot({
  path: path.join(debugDir, "03-after-send.png"),
});

重要: 测试夹具签名提供 { electronApp, po }。要获取页面：

使用 await electronApp.firstWindow() 获取页面
或者使用 po.page 如果 PageObject 暴露它

在失败步骤前后添加截图以了解 UI 在该点的外观。

构建应用（如果需要）:

E2E 测试针对构建的二进制文件运行。如果进行了任何应用代码更改：
```
npm run build
```
如果只更改了测试文件，可以跳过此步骤。

运行测试:

PLAYWRIGHT_RETRIES=0 PLAYWRIGHT_HTML_OPEN=never npm run e2e -- e2e-tests/<testfile>.spec.ts

查看截图:

使用 Read 工具查看捕获的 PNG 截图。Claude Code 可以直接读取和显示图像：
```
Read the PNG files in e2e-tests/debug-screenshots/
```
分析截图以了解：
- 预期的 UI 元素是否可见？
- 是否有错误对话框或意外状态？
- 加载微调器是否仍在显示？
- 布局是否正确？
检查 Playwright 跟踪（用于额外上下文）:

Playwright 配置有 trace: "retain-on-failure"。如果测试失败，跟踪文件将在 test-results/ 中。可以参考此文件以获取额外调试上下文。
迭代:

基于截图所见：
- 如果需要，添加更多有针对性的截图
- 修复测试或应用代码中的问题
- 重新运行以验证
清理:

调试完成后，删除调试截图和添加到测试中的任何临时截图代码：
```
rm -rf e2e-tests/debug-screenshots/
```
删除为调试目的添加的任何 page.screenshot() 调用。
报告发现:

告诉用户：
- 截图揭示了测试失败的什么信息
- 应用了什么修复（如果有）
- 测试现在是否通过