zclaw_openfang/desktop/tests/e2e/KNOWN_ISSUES.md

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

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

## 当前状态

### 测试结果摘要
- **总测试**: 74
- **通过**: 65
- **失败**: 9

### 快速运行测试命令
```bash
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 完成
```typescript
// 在 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: 在测试中增加等待时间
```typescript
// 在 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 返回数据
```bash
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. 修复后运行测试验证
```