企业官网建设流程全解析

如果你要给一个功能复杂的 AI Agent 平台做回归测试，应该测什么、怎么保证"测到了"？开源项目ibl.ai（os）给出了一个教科书级答案：它用Playwright构建了以"用户旅程（Journey）"为核心组织的端到端测试（E2E Testing）体系，目前共收录102 条旅程、近千个检查点（Checkpoint），覆盖从注册登录、实时聊天、语音通话到嵌入组件、可访问性的几乎全部用户场景。本文带你拆解这套 ibl.ai 端到端测试体系的四大设计精髓。

ibl.ai 是什么？为什么它的 E2E 测试这么"重"

ibl.ai（os）是一个让企业创建和部署可定制 AI Agent的开源平台：多 LLM 供应商接入、实时聊天与语音、文档训练、数据分析、用户管理、SSO 认证、可嵌入网页的聊天组件，技术栈为 React 19 + Redux Toolkit + Radix UI + Tailwind CSS。

功能面越宽，"改了 A 功能坏了 B 功能"的风险越高。ibl.ai 的做法是：把每一个用户可见的操作都变成一条可执行的回归检查，并且用台账把"测了什么"公开化。

设计一：把"用户旅程"变成一等公民

所有 E2E 用例集中在 e2e/journeys/ 目录，以编号命名，一条旅程对应一个 spec 文件、一个完整用户故事：

而真正让人眼前一亮的是覆盖台账：

• e2e/COVERAGE.md —— 人类可读的检查点清单，每个检查点就是一句具体的用户操作描述，用[x]标记测试是否已落地
• e2e/coverage.json —— 机器可读的同一份台账，汇总当前为102 条旅程、999 个检查点（954 个已覆盖）

每个检查点都有明确状态：covered（已覆盖）、pending（计划中）、not-reproducible（环境无法复现，已降级到单元测试）、deprecated（功能下线但保留记录）。覆盖率 = 已覆盖 ÷ 有效总数。这样"没测什么"和"测了什么"一样透明，测试缺口不再是黑箱。

设计二：多浏览器并行 + 登录状态一次复用

[ e2e/playwright.config.ts ](e2e/playwright.config.ts) 是整个体系的"总开关"，关键设计有四个：

1. 四浏览器矩阵：Chrome / Firefox / Safari / Edge 各生成独立 project，同一套旅程跑遍所有浏览器；
2. 登录只做一次：auth.setup.ts完成真实登录后把 cookie 存为storageState，后续所有测试项目直接复用，省掉每条用例重复登录的开销；
3. 依赖编排：Playwright 的dependencies/teardown机制串起"登录 → 数据快照 → 跑旅程 → 数据清算"的完整流水线；
4. 自动拉起被测环境：webServer配置会自动启动开发服务器，以及 e2e/utils/embed-harness-server.mjs 这个"第二来源"静态服务器——专门给嵌入组件（Embed Widget）测试提供真正的跨域 iframe 宿主页，模拟客户网站的真实嵌入场景。

CI 中自动重试 2 次、单 worker 保证稳定；本地默认 4 个并行 worker 提速。运行方式非常直接：

pnpm test:e2e # 跑全部旅程 pnpm test:e2e:ui # 交互式 UI 模式 pnpm test:e2e:headed # 可见浏览器调试

设计三：四层"零残留"数据清理系统

AI 平台的测试有个特殊难题：测试会真的创建 Agent、项目等数据，跑完不清理就会污染环境。ibl.ai 用四层保证"跑完即清零"，任何一层都不是可选的：

1. 统一 API 契约：e2e/utils/dm-api.ts 从被测应用自身的真实流量中"观测"后端基址，所有清理路径共用这一个解析逻辑，绝不误伤生产环境；
2. 创建即登记：页面对象在应用确认创建成功的那一刻就把资源写入本次运行的台账（e2e/.residue/<runId>.jsonl），确保即使断言失败，资源也已入册；
3. 工作区只记账不删除：并行 worker 之间不互相删数据，避免竞态；
4. 运行级快照 + 统一清算：旅程全部跑完后，teardown 一次性删除台账中的所有资源、逐个验证 404，并打印前后数量对比；CI 下开启严格模式后，数量有差异直接判失败。

兜底层还有 e2e/utils/mentor-sweeper.ts 等清扫器，回收超过 30 分钟的历史残留——即使某次运行崩溃，数据也不会永远留着。

设计四：覆盖守卫，让"漏测"无法合入

e2e/scripts/check-journey-coverage.mjs 是这套体系的"守门员"，它校验四件事：台账里的每个 spec 文件真实存在、新增页面路由必须映射到至少一条旅程、变更的源码文件能追溯到旅程、检查点总数不许回退。pre-push 钩子和 CI 工作流会用它拦截存在覆盖缺口的提交。

CI 侧则基于 e2e/Dockerfile：直接使用 Playwright 官方镜像 + pnpm 锁定安装，保证每次运行的浏览器行为一致。

这些旅程到底在测什么？

随手几条就能感受到颗粒度：

• 旅程 6（管理员管理 Agent）：改 LLM 供应商、应用自定义 CSS/JS、编辑系统提示词、删除 Agent——对应下面这张 Edit Agent 设置界面里的每个 Tab；
• 旅程 24（记忆 Tab）：完整的记忆增删改 + 分类管理生命周期；
• 旅程 25（MCP Tab）：为 Agent 添加、删除 MCP 连接器；
• 旅程 59（电商积分）：用 Stripe 测试卡4242…走完整"注册 → 扣费 → 余额归零 → 升级付费"闭环；
• 旅程 9 / 9b（语音）：用--use-file-for-fake-audio-capture注入真实音频，测通真实 STT 往返链路。

甚至测试用的素材本身都是真实文件：比如旅程 75 上传的这张 PNG，就是存放在 e2e/files/testing_folder/ 里被真实上传验证的测试资产。

数据集上传E2E旅程真实使用的PNG测试素材文件

此外还有一个兄弟套件 e2e-tauri/：用 WebdriverIO 驱动 Tauri 桌面二进制，补上 Playwright 和单元测试都覆盖不到的桌面 IPC 场景，并且镜像了同一套覆盖台账——连桌面端也享受"检查点即契约"的待遇。

实战指南：如何运行并新增一个检查点

本地运行（详见 e2e/README.md）：

pnpm install && npx playwright install cp e2e/.env.example e2e/.env.development # 填入 AUTH_HOST、MENTOR_NEXTJS_HOST 等变量 pnpm test:e2e

新增检查点只需三步：

1. 在 e2e/COVERAGE.md 对应旅程下追加一条用户操作描述；
2. 在 e2e/journeys/ 的对应 spec 中写好 Playwright 用例（优先复用 page-objects 与 SDK 官方 helper）；
3. 用例通过后把检查点标记为[x]——pre-push 钩子会替你把关，防止"台账上画了饼，代码里没实现"。

小结

ibl.ai 的 E2E 体系给出的启示可以浓缩成三句话：用旅程思维组织用例，用公开台账量化覆盖，用四层清理和自动守卫把"测试可信"变成工程约束。这套以 102 条 Playwright 旅程、近千个检查点为骨架的端到端测试设计，正是复杂 AI Agent 平台能够频繁迭代、放心交付的底气所在。