OpenRoom质量红线:Vitest单测 + Playwright E2E + 90%覆盖率的测试体系全解

原创2026-10-12 18:33:091,870 阅读
文章标签:人工智能AI AgentAI 应用工具调用交互助手前端桌面应用代码生成Vibe Coding微前端

OpenRoom质量红线:Vitest单测 + Playwright E2E + 90%覆盖率的测试体系全解

OpenRoom 是一个运行在浏览器里的 AI Agent 桌面系统——用户用自然语言指挥 AI 操作桌面上的各个应用。这样一个"AI 替你操作软件"的项目,质量如何保障?答案是:Vitest 单元测试 + Playwright E2E 端到端测试 + 90% 覆盖率红线的三层测试体系。本文带你快速看懂这套体系的设计思路与运行方式。

为什么 OpenRoom 需要严格的质量红线?🧪

OpenRoom 的核心链路是:用户说一句话 → LLM 理解意图 → Agent 向各应用下发操作指令 → 桌面 UI 真实变化。任何一环出错,体验都是断裂的。因此项目在 CLAUDE.md 中明确了"任务完成质量标准(mandatory)":

  1. ✅ 受影响包的单元测试必须全部通过
  2. ✅ 本次改动代码的覆盖率必须 > 90%
  3. ✅ 受影响用户流的 E2E 覆盖必须完整,不能只做冒烟测试
  4. ✅ 交付时必须报告确切的验证命令和结果

最低预期:只要单测红了、改动代码覆盖率低于 90%、或 E2E 覆盖不完整,任务就不能算"完成"。

OpenRoom 浏览器桌面测试对象:Chess 应用背景图

第一层:Vitest 单元测试架构

OpenRoom Vitest 单元测试覆盖率数据监控示意图

单元测试集中在 apps/webuiapps/src/lib/tests/ 目录下,共 7 个测试文件,覆盖核心库逻辑:

测试文件 测试对象
llmClient.test.ts LLM 多厂商客户端(OpenAI / Anthropic / llama.cpp 等)
configPersistence.test.ts 配置持久化与旧格式迁移
chatHistoryStorage.test.ts 会话聊天历史存取
imageGenClient.test.ts 图像生成配置加载/保存
logPlugin.test.ts 日志中间件与格式化
logger.test.ts 调试日志开关行为
vibeContainerMock.test.ts Agent 指令分发的事件驱动时序

覆盖率阈值配置

核心配置在 apps/webuiapps/vitest.config.ts,几个关键设计:

  • 测试环境:happy-dom 提供 localStorage、fetch 等浏览器全局对象,无需启动真实浏览器
  • 覆盖率引擎:istanbul,输出 text、lcov、html 三种报告
  • 模块别名:把 @gui/vibe-container 别名指向 mock 文件,实现微前端容器依赖隔离
指标 Vitest 阈值 质量红线(CLAUDE.md)
行覆盖(lines) 75% 改动代码 > 90%
函数覆盖(functions) 85% 改动代码 > 90%
分支覆盖(branches) 70% 改动代码 > 90%

注意一个细节:配置文件阈值是"保底线",而质量红线要求本次改动区域覆盖率必须超过 90%,两者不冲突——前者防止整体退化,后者防止新代码"裸奔"。

Mock 策略:不碰真实 API,不碰真实磁盘 🎭

单测最大的敌人是不确定性。OpenRoom 的测试文件头部通常有清晰的 Mock 策略注释,例如 llmClient.test.ts 的做法:

  • Mock 网络:用 vi.fn() 替换 globalThis.fetch,手工构造 OpenAI / Anthropic 格式的假响应,绝不发起真实 LLM 请求
  • 模块级 Mock:vibeContainerMock.test.ts 用 vi.mock 隔离 diskStorage(NAS 存储)、logger、i18next 等外部依赖
  • 假计时器:vi.useFakeTimers() 精确控制 Agent 指令分发的异步时序,避免"固定延时"的脆弱断言
  • 干净的隔离:beforeEach 中 localStorage.clear() + vi.restoreAllMocks(),保证每个用例互不污染

第二层:Playwright E2E 端到端测试

OpenRoom Playwright E2E 自动化测试巡检用户流程示意图

E2E 配置位于根目录 playwright.config.ts,测试代码在 e2e/app.spec.ts。它模拟真实用户,在 Chromium 中走完核心桌面流程:

测试组 验证内容
Shell 主界面 页面标题、桌面图标 ≥ 5 个、聊天/语言/壁纸/报告四个控制按钮可见
聊天面板可见性 默认显示 → 点击隐藏 → 再显示;面板内要么是配置提示、要么是真实消息
设置弹窗 打开 LLM Settings 弹窗,Cancel 可关闭
输入交互 输入为空时发送按钮禁用,输入后启用;发送后消息入列表且输入框清空
应用窗口 双击应用图标打开窗口,关闭按钮移除窗口
语言切换 EN ↔ ZH 往返切换

几个值得一提的工程细节:

  • 自动拉起开发服务器:webServer 配置自动执行 pnpm dev 并等待 http://localhost:3000 就绪,本地已有服务器则直接复用——跑 E2E 前无需手动启动任何服务
  • CI 友好:CI 环境下 forbidOnly 防止误提交的 .only、失败自动重试 2 次、trace: 'on-first-retry' 记录首次重试的完整操作轨迹,配合 HTML 报告快速定位问题
  • 稳定选择器:断言全部基于 data-testid(如 [data-testid="chat-panel"]),而非脆弱的类名或纯文本,UI 重构不易导致测试误报

自己动手:三步跑起完整测试流水线 🚀

# 1. 获取代码
git clone https://gitcode.com/gh_mirrors/op/OpenRoom
cd OpenRoom && pnpm install

# 2. 运行 Vitest 单元测试(含覆盖率)
cd apps/webuiapps && pnpm test:coverage

# 3. 返回根目录运行 Playwright E2E(自动启动 dev server)
cd .. && pnpm test:e2e        # 无头模式,仅 Chromium
pnpm test:e2e:ui             # 交互式 UI 模式,便于调试

对应的脚本定义分别在 apps/webuiapps/package.json(test / test:watch / test:coverage)和根目录 package.json(test:e2e / test:e2e:ui)中。

总结:这套测试体系的可借鉴之处 ✅

OpenRoom 的测试体系给新手开发者的三个启示:

  1. 分层守门:单测守住"逻辑正确",E2E 守住"用户路径可用",覆盖率红线守住"新代码不裸奔",三者缺一不可
  2. 确定性优先:Mock 掉网络与存储、用假计时器控制时序,让测试快、稳、可重复
  3. 选择器即契约:data-testid 是组件与测试之间的契约,UI 变了测试也不至于全线飘红

如果你正在为自己基于 React + AI Agent 的项目搭建质量保障,OpenRoom 这套 Vitest 单测 + Playwright E2E + 90% 覆盖率的完整方案,值得直接参考。

登录后查看全文
OpenRoom