12 KiB

Raw Blame History

title	date	plan_type	origin	depth
feat: 全项目 E2E 测试套件 + CI workflow	2026-06-28	feat	docs/solutions/integration-issues/jwt-secret-dev-mode-user-id-mismatch.md	deep

feat: 全项目 E2E 测试套件 + CI workflow

Summary

建立覆盖全项目的 E2E 测试体系，包括前端所有关键视图的 Playwright spec、后端 API/WS 闭环测试、认证状态持久化测试、数据一致性测试，以及 GitHub Actions/Gitea CI workflow。目标：让本次出现的 reload 登录失效、日历数据不一致、对话无法删除等问题在 CI 阶段就被捕获，不再流入用户手中。

Problem Frame

当前项目虽有测试基础设施（后端 tests/e2e/ + 前端 Playwright 4 spec），但存在严重缺口：

认证状态持久化未测：reload 后登录态保持、token 跨重启持久化、refresh token 冷启动 — 这些场景无 E2E 覆盖，导致问题4（reload 跳登录页）长期未发现
数据一致性未测：agent 通过工具创建数据（如日历事件）后，UI 能否看到 — 无端到端验证，导致问题2（日历事件看不到）长期未发现
前端视图覆盖不足：仅 login/chat/calendar/terminal 4个 spec，skills/documents/bitable/evolution/monitor/settings/admin 等视图零覆盖
CI 完全无测试：.github/workflows/ 和 .gitea/workflows/ 都没有测试 job，所有测试依赖开发者手动运行
对话管理 CRUD 未测：创建、删除、切换对话的端到端流程未覆盖，导致问题1（对话无法删除）长期未发现

Requirements

R1: 认证状态持久化 E2E — 覆盖 reload、token 跨重启、refresh token 冷启动
R2: 数据一致性 E2E — 覆盖 agent 工具创建数据后 UI 可见性（日历优先）
R3: 对话管理 CRUD E2E — 覆盖创建、删除、切换、历史加载
R4: 前端全视图 E2E — 覆盖 skills/documents/bitable/evolution/monitor/settings/admin
R5: 后端 API E2E 补充 — 覆盖未测的 REST 端点（experts/mcp/workflows 等）
R6: CI workflow — GitHub Actions + Gitea 自动运行测试

Key Technical Decisions

KTD1: Playwright 作为前端 E2E 主框架。项目已安装 @playwright/test@^1.59.0 且配置完善（双服务器自动启动、global-setup 创建测试用户），无需引入新框架。扩展新 spec 复用现有 helpers.ts。
KTD2: 后端 E2E 复用 tests/e2e/conftest.py 基础设施。MockLLMProvider + 端口 18765 + scripts/run_e2e.sh 已成熟，新测试直接扩展。不引入 testcontainers（项目已声明但未使用，保持一致性）。
KTD3: CI 用 docker-compose.test.yml 启动依赖。PostgreSQL pgvector (5434) + Redis (6381) 已配置，CI 中 docker-compose -f docker-compose.test.yml up -d 即可。不引入 testcontainers 以保持与本地环境一致。
KTD4: 认证状态测试用 page.reload() + evaluate 验证 localStorage。不 mock Tauri Keychain（Web 模式下走 localStorage fallback），直接验证持久化行为。
KTD5: 数据一致性测试用 "agent 路径写入 + UI 路径读取" 双向验证。先通过 API/WS 让 agent 创建日历事件，再通过 UI 验证事件可见。这是本次问题的核心回归测试。

U1. 认证状态持久化 E2E

Goal: 验证登录状态跨 reload、跨服务器重启持久化，捕获问题4（reload 跳登录页）的回归。

Requirements: R1

Dependencies: 无

Files:

src/agentkit/server/frontend/e2e/auth-persistence.spec.ts (create)
src/agentkit/server/frontend/e2e/helpers.ts (modify — 添加 reloadAndWaitAuth helper)

Approach:

测试1：登录 → reload → 验证仍处于已认证状态（不跳 login）
测试2：登录 → 清除 localStorage → reload → 验证跳 login
测试3：登录 → 服务器重启（Playwright 无法直接重启服务器，改为验证 token 过期场景）→ 验证 refresh token 冷启动
测试4：登录 → 访问受保护页面 → 验证 Authorization header 携带 access token
测试5：登录 → 等待 access token 过期（mock 时间或短 TTL）→ 验证 silent refresh

Patterns to follow: e2e/login.spec.ts 的 loginViaApi + loginAndHydrate 模式

Test scenarios:

Happy path: 登录后 reload 保持登录态
Edge case: localStorage 为空时 reload 跳 login
Error path: refresh token 无效时跳 login 并清除存储
Integration: access token 过期时自动 refresh，不中断用户操作

Verification: npm run test:e2e -- --grep "auth-persistence" 全部通过

U2. 对话管理 CRUD E2E

Goal: 验证对话的创建、删除、切换、历史加载端到端流程，捕获问题1（对话无法删除）的回归。

Requirements: R3

Dependencies: U1

Files:

src/agentkit/server/frontend/e2e/conversation-management.spec.ts (create)

Approach:

测试1：新建对话 → 发送消息 → 验证对话出现在列表
测试2：删除对话 → 验证从列表消失 → reload → 验证不再出现（未被"复活"）
测试3：多对话切换 → 验证消息历史正确加载
测试4：删除当前活跃对话 → 验证自动切换到下一个或新建
测试5：删除所有对话 → 验证空状态显示

Patterns to follow: e2e/chat.spec.ts 的 sendChatMessage + waitForLlmResponse 模式

Test scenarios:

Happy path: 创建 → 发消息 → 删除 → 验证消失
Edge case: 删除进行中的对话（pending 状态）
Error path: 删除不存在的对话（404）→ UI 正确处理
Integration: 多对话切换时消息历史隔离

Verification: npm run test:e2e -- --grep "conversation-management" 全部通过

U3. 日历数据一致性 E2E

Goal: 验证 agent 通过 calendar 工具创建事件后，UI 日历视图能显示该事件，捕获问题2（日历事件看不到）的回归。

Requirements: R2

Dependencies: U1

Files:

src/agentkit/server/frontend/e2e/calendar-data-consistency.spec.ts (create)

Approach:

测试1：通过 chat 让 agent 创建日历事件（"帮我创建下周一上午10点的项目会议"）→ 切换到日历视图 → 验证事件可见
测试2：通过 UI 创建事件 → 通过 API 查询 → 验证 user_id 一致
测试3：通过 chat 创建事件 → 通过 API 查询 → 验证 user_id 不是 hallucinate 值（"default"/"zhangsan"）
测试4：多事件场景 → 验证日历正确渲染所有事件
测试5：删除事件 → 验证 UI 和 API 同步消失

Patterns to follow: e2e/calendar.spec.ts 的 E1-E8 模式 + e2e/chat.spec.ts 的 agent 交互

Test scenarios:

Happy path: agent 创建 → UI 可见
Data integrity: user_id 一致性（agent 路径 vs UI 路径）
Edge case: agent 创建事件但 LLM 未提供 user_id → 使用 default_user_id
Integration: UI 创建 + agent 创建混合场景

Verification: npm run test:e2e -- --grep "calendar-data-consistency" 全部通过

U4. 前端全视图 E2E 补充

Goal: 为 skills/documents/bitable/evolution/monitor/settings/admin 视图补充 E2E spec，确保所有关键视图可访问且基本功能正常。

Requirements: R4

Dependencies: U1

Files:

src/agentkit/server/frontend/e2e/skills-view.spec.ts (create)
src/agentkit/server/frontend/e2e/documents-view.spec.ts (create)
src/agentkit/server/frontend/e2e/bitable-view.spec.ts (create)
src/agentkit/server/frontend/e2e/evolution-view.spec.ts (create)
src/agentkit/server/frontend/e2e/monitor-view.spec.ts (create)
src/agentkit/server/frontend/e2e/settings-view.spec.ts (create)
src/agentkit/server/frontend/e2e/admin-view.spec.ts (create)

Approach: 每个视图至少覆盖：

页面加载（无白屏、无 401）
核心功能（如 skills 列表加载、documents 上传按钮可见等）
导航交互（侧边栏切换、标签页切换）
错误状态（空数据、加载失败）

Patterns to follow: e2e/calendar.spec.ts 的 E1（面板加载）模式

Test scenarios: 每个视图 3-5 个测试（加载、核心功能、空状态、错误处理）

Verification: npm run test:e2e 全部 spec 通过

U5. 后端 API E2E 补充

Goal: 补充未覆盖的后端 REST 端点 E2E 测试（experts/mcp/workflows/llm gateway 等）。

Requirements: R5

Dependencies: 无

Files:

tests/e2e/test_api_coverage.py (create)

Approach:

遍历 /api/v1/ 下所有路由前缀
对未覆盖的端点编写基础 E2E（健康检查、认证要求、CRUD 基础）
重点覆盖：/experts、/mcp、/workflows、/llm/chat（SSE）、/config、/system

Patterns to follow: tests/e2e/test_basic_api.py 的 api_client fixture 模式

Test scenarios:

Happy path: 每个端点的基础 GET/POST 返回预期状态码
Auth: 受保护端点无 token 返回 401
Error path: 无效参数返回 4xx

Verification: python3 -m pytest tests/e2e/test_api_coverage.py -v 通过

U6. CI workflow 建立

Goal: 在 GitHub Actions 和 Gitea Actions 中建立测试 workflow，自动运行后端 pytest + 前端 vitest + Playwright E2E。

Requirements: R6

Dependencies: U1, U2, U3, U4, U5

Files:

.github/workflows/test.yml (create)
.gitea/workflows/test.yml (create)

Approach:

GitHub Actions workflow：
- Trigger: push to main/develop, PR to main
- Jobs: backend-test (pytest) + frontend-unit (vitest) + frontend-e2e (playwright)
- Services: PostgreSQL (pgvector) + Redis via docker-compose.test.yml
- Cache: pip + npm 依赖缓存
Gitea Actions workflow：同上（Gitea 兼容 GitHub Actions 语法）

Patterns to follow: 标准 GitHub Actions Python + Node.js workflow 模式

Test scenarios:

Happy path: PR 触发 workflow，所有测试通过
Failure: 故意引入 bug，验证测试失败并阻止合并

Verification: 推送分支 → CI 自动运行 → 全绿

Scope Boundaries

In scope

前端 Playwright E2E spec（认证持久化、对话管理、日历一致性、全视图覆盖）
后端 API E2E 补充（未覆盖端点）
CI workflow（GitHub Actions + Gitea）

Deferred to Follow-Up Work

Tauri 桌面端 E2E（需引入 tauri-driver，当前无基础设施）
真实 LLM E2E 扩展（成本高，保持现有 mock 策略）
性能/负载测试（本次聚焦功能正确性）
视觉回归测试（Percy/Chromatic，后续补充）

Non-goals

重写现有测试框架
引入 testcontainers（保持与现有 docker-compose.test.yml 一致）
修改产品代码（测试发现的问题由 ce-debug 修复）

Risks & Dependencies

Risk	Mitigation
Playwright E2E 执行慢（双服务器启动）	已有 `reuseExistingServer: !CI` 配置，本地复用
MockLLMProvider 响应不匹配新场景	扩展 `MOCK_LLM_RESPONSES` 字典，新增 calendar 场景
CI 中 PostgreSQL pgvector 版本不匹配	docker-compose.test.yml 已指定 `pgvector/pgvector:pg15`
calendar.spec.ts 已知 cold-start bug（refresh token）	新 spec 使用 UI 表单登录，避开 localStorage 注入

System-Wide Impact

开发者工作流：PR 将自动触发 CI 测试，需要开发者在本地运行测试后再推送
部署流程：CI 绿灯成为部署前置条件
测试维护：新增 spec 需要维护，helpers.ts 扩展需保持向后兼容

Open Questions

无 — 范围和 CI 策略已确认。

Deferred to Implementation

各 spec 的具体选择器（需实际查看 DOM 结构）
MockLLMProvider 的新场景响应内容
CI workflow 的具体缓存键值
各视图 spec 的详细测试用例（需查看实际 UI）

12 KiB Raw Blame History Unescape Escape

feat: 全项目 E2E 测试套件 + CI workflow

Summary

Problem Frame

Requirements

Key Technical Decisions

U1. 认证状态持久化 E2E

U2. 对话管理 CRUD E2E

U3. 日历数据一致性 E2E

U4. 前端全视图 E2E 补充

U5. 后端 API E2E 补充

U6. CI workflow 建立

Scope Boundaries

In scope

Deferred to Follow-Up Work

Non-goals

Risks & Dependencies

System-Wide Impact

Open Questions

Deferred to Implementation

12 KiB

Raw Blame History