OpenRoom质量红线:Vitest单测 + Playwright E2E + 90%覆盖率的测试体系全解
OpenRoom质量红线:Vitest单测 + Playwright E2E + 90%覆盖率的测试体系全解
OpenRoom 是一个运行在浏览器里的 AI Agent 桌面系统——用户用自然语言指挥 AI 操作桌面上的各个应用。这样一个"AI 替你操作软件"的项目,质量如何保障?答案是:Vitest 单元测试 + Playwright E2E 端到端测试 + 90% 覆盖率红线的三层测试体系。本文带你快速看懂这套体系的设计思路与运行方式。
为什么 OpenRoom 需要严格的质量红线?🧪
OpenRoom 的核心链路是:用户说一句话 → LLM 理解意图 → Agent 向各应用下发操作指令 → 桌面 UI 真实变化。任何一环出错,体验都是断裂的。因此项目在 CLAUDE.md 中明确了"任务完成质量标准(mandatory)":
- ✅ 受影响包的单元测试必须全部通过
- ✅ 本次改动代码的覆盖率必须 > 90%
- ✅ 受影响用户流的 E2E 覆盖必须完整,不能只做冒烟测试
- ✅ 交付时必须报告确切的验证命令和结果
最低预期:只要单测红了、改动代码覆盖率低于 90%、或 E2E 覆盖不完整,任务就不能算"完成"。
第一层: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 端到端测试
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 的测试体系给新手开发者的三个启示:
- 分层守门:单测守住"逻辑正确",E2E 守住"用户路径可用",覆盖率红线守住"新代码不裸奔",三者缺一不可
- 确定性优先:Mock 掉网络与存储、用假计时器控制时序,让测试快、稳、可重复
- 选择器即契约:
data-testid是组件与测试之间的契约,UI 变了测试也不至于全线飘红
如果你正在为自己基于 React + AI Agent 的项目搭建质量保障,OpenRoom 这套 Vitest 单测 + Playwright E2E + 90% 覆盖率的完整方案,值得直接参考。


