CLAUDE.md

1# E2E Testing Guide for Claude
2 
3本文档记录了在 LobeHub E2E 测试开发中的经验和最佳实践。
4 
5Related: [LOBE-2417](https://linear.app/lobehub/issue/LOBE-2417/建立核心产品功能-e2e-测试体验基准线)
6 
7## 测试策略：体验驱动的 E2E 测试
8 
9### 核心理念
10 
11建立完整的**用户体验链路 E2E 测试**，作为未来变更和重构的**体验基准线**。
12 
13**目的**：
14 
15- 确保核心用户体验在代码变更后不会退化
16- 为重构提供安全网，敢于大胆改进代码
17- 从用户视角验证功能完整性
18 
19### 产品架构覆盖
20 
21| 模块             | 子功能                            | 优先级 | 状态 |
22| ---------------- | --------------------------------- | ------ | ---- |
23| **Agent**        | Builder, 对话，Task               | P0     | 🚧   |
24| **Agent Group**  | Builder, 群聊                     | P0     | ⏳   |
25| **Page（文稿）** | 侧边栏 CRUD ✅，文档编辑，Copilot | P0     | 🚧   |
26| **知识库**       | 创建，上传，RAG 对话              | P1     | ⏳   |
27| **记忆**         | 查看，编辑，关联                  | P2     | ⏳   |
28 
29### 标签系统
30 
31```gherkin
32@journey      # 用户旅程测试（体验基准线）
33@smoke        # 冒烟测试（快速验证）
34@regression   # 回归测试
35 
36@P0           # 最高优先级（CI 必跑）
37@P1           # 高优先级（Nightly）
38@P2           # 中优先级（发版前）
39 
40@agent        # Agent 模块
41@agent-group  # Agent Group 模块
42@page         # Page 文稿模块
43@knowledge    # 知识库模块
44@memory       # 记忆模块
45```
46 
47### 执行策略
48 
49```bash
50# CI - P0 冒烟测试（每次 PR）
51pnpm exec cucumber-js --config cucumber.config.js --tags "@smoke and @P0"
52 
53# Nightly - 所有用户旅程
54pnpm exec cucumber-js --config cucumber.config.js --tags "@journey"
55 
56# 发版前 - 完整回归
57pnpm exec cucumber-js --config cucumber.config.js --tags "@P0 or @P1"
58 
59# 完整测试
60pnpm exec cucumber-js --config cucumber.config.js
61```
62 
63### 测试设计原则
64 
651. **按 CRUD + 核心交互覆盖**：每个模块覆盖创建、读取、更新、删除及核心交互流程
662. **LLM 响应必须 Mock**：保证测试稳定性和可重复性
673. **中文描述场景**：Feature 文件使用中文，贴近产品需求
684. **优先级分层**：合理分配 P0/P1/P2，控制 CI 执行时间
69 
70## 目录结构
71 
72```
73e2e/
74├── src/
75│   ├── features/                    # Cucumber feature 文件
76│   │   ├── journeys/                # 用户旅程（体验基准线）
77│   │   │   ├── agent/
78│   │   │   │   ├── agent-builder.feature
79│   │   │   │   ├── agent-conversation.feature  ✅
80│   │   │   │   └── agent-task.feature
81│   │   │   ├── agent-group/
82│   │   │   │   ├── group-builder.feature
83│   │   │   │   └── group-chat.feature
84│   │   │   ├── page/
85│   │   │   │   └── page-crud.feature  ✅
86│   │   │   ├── knowledge/
87│   │   │   │   └── knowledge-rag.feature
88│   │   │   └── memory/
89│   │   │       └── memory-crud.feature
90│   │   ├── smoke/                   # 冒烟测试
91│   │   │   └── discover/
92│   │   └── regression/              # 回归测试
93│   ├── steps/                       # Step definitions
94│   │   ├── agent/                   # Agent 相关 steps
95│   │   ├── page/                    # Page 相关 steps
96│   │   ├── common/                  # 通用 steps (auth, navigation)
97│   │   └── hooks.ts                 # Before/After hooks
98│   ├── mocks/                       # Mock 框架
99│   │   └── llm/                     # LLM Mock (拦截 AI 请求) ✅
100│   └── support/                     # 测试支持文件
101│       └── world.ts                 # CustomWorld 定义
102├── screenshots/                     # 失败截图
103├── reports/                         # 测试报告
104├── cucumber.config.js               # Cucumber 配置
105└── CLAUDE.md                        # 本文档
106```
107 
108## 本地环境启动
109 
110> 详细流程参考 [e2e/docs/local-setup.md](./docs/local-setup.md)
111 
112### 一键启动（推荐）
113 
114使用 TypeScript 脚本自动完成环境设置：
115 
116```bash
117# 在项目根目录运行
118 
119# 仅设置数据库（启动 PostgreSQL + 运行迁移）
120bun e2e/scripts/setup.ts
121 
122# 设置数据库并启动服务器
123bun e2e/scripts/setup.ts --start
124 
125# 完整设置（数据库 + 构建 + 启动服务器）
126bun e2e/scripts/setup.ts --build --start
127 
128# 清理环境
129bun e2e/scripts/setup.ts --clean
130```
131 
132### 脚本选项
133 
134| 选项             | 说明                         |
135| ---------------- | ---------------------------- |
136| `--clean`        | 清理现有容器和进程           |
137| `--skip-db`      | 跳过数据库设置（使用已有的） |
138| `--skip-migrate` | 跳过数据库迁移               |
139| `--build`        | 启动前构建应用               |
140| `--start`        | 设置完成后启动服务器         |
141| `--port <port>`  | 服务器端口（默认 3006）      |
142 
143**重要提示**:
144 
145- 必须使用 `paradedb/paradedb:latest` 镜像（支持 pgvector 扩展）
146- 服务器必须在**项目根目录**启动，不能在 e2e 目录
147- S3 环境变量是**必需**的，即使不测试文件上传（脚本已自动处理）
148 
149## 运行测试
150 
151```bash
152# 从 e2e 目录运行
153cd e2e
154 
155# 运行特定标签的测试
156BASE_URL=http://localhost:3006 \
157  DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres \
158  pnpm exec cucumber-js --config cucumber.config.js --tags &quot;@AGENT-CHAT-001&quot;
159 
160# 调试模式（显示浏览器）
161HEADLESS=false BASE_URL=http://localhost:3006 \
162  DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres \
163  pnpm exec cucumber-js --config cucumber.config.js --tags &quot;@conversation&quot;
164 
165# 运行所有测试
166BASE_URL=http://localhost:3006 \
167  DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres \
168  pnpm exec cucumber-js --config cucumber.config.js
169```
170 
171**重要**: 必须显式指定 `--config cucumber.config.js`，否则配置不会被正确加载。
172 
173## LLM Mock 实现
174 
175### 核心原理
176 
177LLM Mock 通过 Playwright 的 `page.route()` 拦截对 `/webapi/chat/openai` 的请求，返回预设的 SSE 流式响应。
178 
179### SSE 响应格式
180 
181LobeHub 使用特定的 SSE 格式，必须严格匹配：
182 
183```typescript
184// 1. 初始 data 事件
185id: msg_xxx
186event: data
187data: {"id":"msg_xxx","model":"gpt-4o-mini","role":"assistant","type":"message",...}
188 
189// 2. 文本内容分块（text 事件）
190id: msg_xxx
191event: text
192data: "Hello"
193 
194id: msg_xxx
195event: text
196data: "! I am"
197 
198// 3. 停止事件
199id: msg_xxx
200event: stop
201data: "end_turn"
202 
203// 4. 使用量统计
204id: msg_xxx
205event: usage
206data: {"totalTokens":100,...}
207 
208// 5. 最终停止
209id: msg_xxx
210event: stop
211data: "message_stop"
212```
213 
214### 使用示例
215 
216```typescript
217import { llmMockManager, presetResponses } from '../../mocks/llm';
218 
219// 在测试步骤中设置 mock
220llmMockManager.setResponse('hello', presetResponses.greeting);
221await llmMockManager.setup(this.page);
222```
223 
224### 添加自定义响应
225 
226```typescript
227// 为特定用户消息设置响应
228llmMockManager.setResponse('你好', '你好！我是 Lobe AI，有什么可以帮助你的？');
229 
230// 清除所有自定义响应
231llmMockManager.clearResponses();
232```
233 
234## 页面元素定位技巧
235 
236### 富文本编辑器 (contenteditable) 输入
237 
238LobeHub 使用 `@lobehub/editor` 作为聊天输入框，是一个 contenteditable 的富文本编辑器。
239 
240**关键点**:
241 
2421. 不能直接用 `locator.fill()` - 对 contenteditable 不生效
2432. 需要先 click 容器让编辑器获得焦点
2443. 使用 `keyboard.type()` 输入文本
245 
246```typescript
247// 正确的输入方式
248await chatInputContainer.click();
249await this.page.waitForTimeout(500); // 等待焦点
250await this.page.keyboard.type(message, { delay: 30 });
251await this.page.keyboard.press('Enter'); // 发送
252```
253 
254### 添加 data-testid
255 
256为了更可靠的元素定位，可以在组件上添加 `data-testid`：
257 
258```tsx
259// src/features/ChatInput/Desktop/index.tsx
260<ChatInput
261  data-testid="chat-input"
262  ...
263/>
264```
265 
266## 调试技巧
267 
268### 添加步骤日志
269 
270在每个关键步骤添加 console.log，帮助定位问题：
271 
272```typescript
273Given('用户进入页面', async function (this: CustomWorld) {
274  console.log('   📍 Step: 导航到首页...');
275  await this.page.goto('/');
276 
277  console.log('   📍 Step: 查找元素...');
278  const element = this.page.locator('...');
279 
280  console.log('   ✅ 步骤完成');
281});
282```
283 
284### 查看失败截图
285 
286测试失败时会自动保存截图到 `e2e/screenshots/` 目录。
287 
288### 非 headless 模式
289 
290设置 `HEADLESS=false` 可以看到浏览器操作：
291 
292```bash
293HEADLESS=false pnpm exec cucumber-js --config cucumber.config.js --tags &quot;@smoke&quot;
294```
295 
296## 环境变量
297 
298运行测试需要以下环境变量：
299 
300```bash
301BASE_URL=http://localhost:3010 # 测试服务器地址
302DATABASE_URL=postgresql://...  # 数据库连接
303DATABASE_DRIVER=node           # 数据库驱动
304KEY_VAULTS_SECRET=...          # 密钥
305AUTH_SECRET=...                # Auth 密钥
306 
307# 可选：S3 相关（如果测试涉及文件上传）
308S3_ACCESS_KEY_ID=e2e-mock-access-key
309S3_SECRET_ACCESS_KEY=e2e-mock-secret-key
310S3_BUCKET=e2e-mock-bucket
311S3_ENDPOINT=https://e2e-mock-s3.localhost
312```
313 
314## 清理环境
315 
316测试完成后或需要重置环境时：
317 
318```bash
319# 一键清理（推荐）
320bun e2e/scripts/setup.ts --clean
321```
322 
323或手动清理：
324 
325```bash
326# 停止并删除 PostgreSQL 容器
327docker stop postgres-e2e && docker rm postgres-e2e
328 
329# 清理端口占用
330lsof -ti:3006 | xargs kill -9
331lsof -ti:5433 | xargs kill -9
332```
333 
334## 常见问题
335 
336### 1. 测试超时 (function timed out)
337 
338**原因**: 元素定位失败或等待时间不足
339 
340**解决**:
341 
342- 检查选择器是否正确
343- 增加 timeout 参数
344- 添加显式等待 `waitForTimeout()`
345 
346### 2. strict mode violation (多个元素匹配)
347 
348**原因**: 选择器匹配到多个元素（如 desktop/mobile 双组件）
349 
350**解决**:
351 
352- 使用 `.first()` 或 `.nth(n)`
353- 使用 `boundingBox()` 过滤可见元素
354 
355### 3. LLM Mock 未生效
356 
357**原因**: 路由拦截设置在页面导航之后
358 
359**解决**: 确保在 `page.goto()` 之前调用 `llmMockManager.setup(page)`
360 
361### 4. 输入框内容为空
362 
363**原因**: contenteditable 编辑器的特殊性
364 
365**解决**:
366 
367- 先 click 容器确保焦点
368- 使用 `keyboard.type()` 而非 `fill()`
369- 添加适当的等待时间
370 
371## 编写新测试的流程
372 
3731. **创建 Feature 文件** (`src/features/xxx/xxx.feature`)
374   - 使用中文描述场景
375   - 添加适当的标签 (@journey, @P0, @smoke 等)
376 
3772. **创建 Step Definitions** (`src/steps/xxx/xxx.steps.ts`)
378   - 导入必要的 mock 和工具
379   - 每个步骤添加日志
380   - 处理元素定位的边界情况
381 
3823. **设置 Mock**（如需要）
383   - 在 `src/mocks/` 下创建对应的 mock
384   - 在步骤中初始化 mock
385 
3864. **调试和验证**
387   - 先用 `HEADLESS=false` 运行观察
388   - 检查失败截图
389   - 确保稳定通过后再提交
390