zclaw_openfang/desktop/tests/e2e/KNOWN_ISSUES.md

E2E 测试已知问题与修复指南

最后更新: 2026-03-17 测试通过率: 88% (65/74)

当前状态

测试结果摘要

• 总测试: 74
• 通过: 65
• 失败: 9

快速运行测试命令

cd g:/ZClaw_openfang/desktop

# 运行全部测试
pnpm exec playwright test --config=tests/e2e/playwright.config.ts --reporter=list

# 仅运行 app-verification (全部通过)
pnpm exec playwright test --config=tests/e2e/playwright.config.ts tests/e2e/specs/app-verification.spec.ts --reporter=list

# 仅运行 functional-scenarios
pnpm exec playwright test --config=tests/e2e/playwright.config.ts tests/e2e/specs/functional-scenarios.spec.ts --reporter=list

---

问题 1: 聊天输入禁用问题

现象

测试在尝试填写聊天输入框时失败，因为 Agent 正在回复中 (isStreaming=true)，导致输入框被禁用。

错误信息

locator resolved to <textarea rows="1" disabled placeholder="Agent 正在回复..." ...>
element is not enabled

影响的测试

• 10. 完整用户流程 › 10.2 完整聊天流程
• 11. 性能与稳定性 › 11.4 长时间运行稳定性

修复方案

方案 A: 在测试中等待 streaming 完成

// 在 functional-scenarios.spec.ts 中添加等待逻辑
async function waitForChatReady(page: Page) {
  const chatInput = page.locator('textarea').first();
  // 等待输入框可用
  await page.waitForFunction(() => {
    const textarea = document.querySelector('textarea');
    return textarea && !textarea.disabled;
  }, { timeout: 30000 });
}

方案 B: 在组件中添加可中断的 streaming

修改 ChatArea.tsx 允许用户在 streaming 时中断并输入新消息。

相关文件

• desktop/src/components/ChatArea.tsx:178 - disabled={isStreaming || !input.trim() || !connected}
• desktop/tests/e2e/specs/functional-scenarios.spec.ts:1016 - 失败的测试行

---

问题 2: Hands 列表为空

现象

测试期望找到 Hands 卡片，但实际找到 0 个。API /api/hands 返回数据正常。

错误信息

Found 0 hand cards

影响的测试

• 3. Agent/分身管理 › 3.1 分身列表显示
• 4. Hands 系统 › 4.1 Hands 列表显示

根因分析

1. Hands 数据从 API 加载是异步的
2. 测试可能在数据加载完成前就检查 DOM
3. HandList 组件可能没有正确渲染数据

修复方案

方案 A: 在测试中增加等待时间

// 在 functional-scenarios.spec.ts 中修改
test('4.1 Hands 列表显示', async ({ page }) => {
  await navigateToTab(page, 'Hands');
  await page.waitForTimeout(2000); // 增加等待时间
  await page.waitForSelector('button:has-text("Hand")', { timeout: 10000 });
  // ... 继续测试
});

方案 B: 在 HandList 组件中添加加载状态

确保组件在数据加载时显示 loading 状态，数据加载后正确渲染。

验证 API 返回数据

curl -s http://127.0.0.1:50051/api/hands | head -c 500

相关文件

• desktop/src/components/HandList.tsx - Hands 列表组件
• desktop/src/store/gatewayStore.ts:1175 - loadHands 函数
• desktop/tests/e2e/specs/functional-scenarios.spec.ts:406 - 失败的测试

---

问题 3: 模型配置测试失败

现象

测试在设置页面中找不到模型配置相关的 UI 元素。

影响的测试

• 8. 设置页面 › 8.3 模型配置

修复方案

检查设置页面的模型配置部分是否存在，以及选择器是否正确。

相关文件

• desktop/src/components/Settings/SettingsLayout.tsx
• desktop/tests/e2e/specs/functional-scenarios.spec.ts:729

---

问题 4: 应用启动测试断言失败

现象

测试期望所有导航标签都存在，但可能某些标签未渲染。

影响的测试

• 1. 应用启动与初始化 › 1.1 应用正常启动并渲染所有核心组件

修复方案

调整测试断言，使其更灵活地处理异步加载的组件。

---

API 端点状态

正常工作的端点 (200)

• /api/status - Gateway 状态
• /api/agents - Agent 列表
• /api/hands - Hands 列表
• /api/config - 配置读取
• /api/chat - 聊天 (WebSocket streaming)

返回 404 的端点 (有 fallback 处理)

• /api/workspace
• /api/stats/usage
• /api/plugins/status
• /api/scheduler/tasks
• /api/security/status

这些 404 是预期行为，应用有 fallback 机制处理。

---

测试文件修改记录

已修复的选择器问题

1. 侧边栏导航 - 使用 getByRole('tab', { name: '分身' }) 替代正则匹配
2. 发送按钮 - 使用 getByRole('button', { name: '发送消息' }) 替代模糊匹配
3. Strict mode 问题 - 修复多个 .or() 选择器导致的 strict mode violation

测试配置文件

• desktop/tests/e2e/playwright.config.ts - Playwright 配置
• desktop/tests/e2e/specs/app-verification.spec.ts - 基础验证测试 (28/28 通过)
• desktop/tests/e2e/specs/functional-scenarios.spec.ts - 功能场景测试 (37/46 通过)

---

截图位置

desktop/test-results/screenshots/
desktop/test-results/functional-scenarios-*-chromium/

下一步行动建议

1. 优先级 P0: 修复聊天输入禁用问题 (影响多个测试)
2. 优先级 P1: 修复 Hands 列表渲染问题
3. 优先级 P2: 优化模型配置测试
4. 优先级 P3: 清理长时间运行稳定性测试

---

新会话启动提示

在新会话中，可以使用以下提示快速开始：

我需要继续修复 ZCLAW 桌面应用的 E2E 测试问题。

当前状态:
- 测试通过率 88% (65/74)
- 已知问题记录在 desktop/tests/e2e/KNOWN_ISSUES.md

请帮我:
1. 阅读 KNOWN_ISSUES.md 了解详细问题
2. 从优先级 P0 (聊天输入禁用问题) 开始修复
3. 修复后运行测试验证