LobeHub Desktop 控制器单元测试实战Vitest 下的 Electron 主进程测试体系【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub在 LobeHub 桌面端中主进程控制器Controller承担了菜单、托盘、通知、文件操作、IPC 通道等 Electron 核心职责。本篇指南以仓库内desktop-controller-test测试指南为骨架完整介绍控制器单元测试的目录约定、测试文件结构、外部依赖 Mock 策略与最佳实践并结合 Vitest 配置、全局 Mock 设置 以及 MenuCtr 测试用例 等真实源码帮助读者掌握在 LobeHub Desktop 中编写可运行、可维护的控制器单元测试的完整方案。测试框架与目录结构约定LobeHub Desktop 使用Vitest作为测试框架。控制器单元测试的放置位置有明确约定与控制器源文件相邻的__tests__目录文件名为原控制器文件名加.test.ts后缀。仓库中的实际结构如下apps/desktop/src/main/controllers/ ├── __tests__/ │ ├── index.test.ts │ ├── MenuCtr.test.ts │ └── ... ├── McpCtr.ts ├── MenuCtr.ts └── ...在 apps/desktop/src/main/controllers/ 目录下每个控制器如MenuCtr.ts、ShellCommandCtr.ts、WorkspaceCtr.ts对应__tests__中的同名测试文件如MenuCtr.test.ts、ShellCommandCtr.test.ts、WorkspaceCtr.test.ts形成了严格的“一控制器一测试文件”映射关系。这一约定让读者能快速定位任意控制器的测试覆盖情况。Vitest 的具体配置位于 apps/desktop/vitest.config.mts其中有几个对编写测试至关重要的设定路径别名指向src/main、~common指向src/common测试中可用/core/App这类导入路径直接引用主进程模块与生产代码保持一致运行环境environment: node控制器运行在主进程Node 环境测试无需浏览器 DOM全局设置文件setupFiles: [./src/main/__mocks__/setup.ts]每个测试套件启动前都会先执行该文件为所有测试注入默认的 electron 与日志 Mock后文详述覆盖率使用v8provider报告输出到./coverage/app。控制器与测试基类ControllerModule 的构造约定编写控制器测试前先理解被测对象的形态。所有控制器都继承自 ControllerModuleexport class ControllerModule extends IpcService implements IControllerModule { constructor(public app: App) { super(); this.app app; } }即控制器构造时依赖注入一个App实例。这正是测试中需要 Mock 的核心对象——你无需启动真实 Electron 应用只需构造一个具备控制器所访问属性的mockApp。此外controllers/index.ts 中还定义了IpcMethod()、shortcut()、createProtocolHandler()等装饰器用于把控制器方法注册为 IPC 通道、快捷键或协议处理器仓库中的模板文件 _template.ts 展示了一个带IpcMethod()的最小控制器写法是新增控制器时的参考样板。基础测试文件结构一个标准的控制器测试文件遵循以下骨架继承自原文档模板import { beforeEach, describe, expect, it, vi } from vitest; import type { App } from /core/App; import YourController from ../YourControllerName; // Mock dependencies vi.mock(dependency-module, () ({ dependencyFunction: vi.fn(), })); // Mock App instance const mockApp { // Mock necessary App properties and methods as needed } as unknown as App; describe(YourController, () { let controller: YourController; beforeEach(() { vi.clearAllMocks(); controller new YourController(mockApp); }); describe(methodName, () { it(test scenario description, async () { // Prepare test data // Execute method under test const result await controller.methodName(params); // Verify results expect(result).toMatchObject(expectedResult); }); }); });各部分职责明确vi.mock()声明用工厂函数替换外部依赖模块切断对真实 I/O、Electron API 的依赖mockApp用as unknown as App断言把只含所需属性的对象伪装成完整App——测试只 Mock 被测控制器实际触达的成员beforeEach先vi.clearAllMocks()清空调用记录再重建控制器实例保证用例之间零状态泄漏双层describe外层对应控制器类内层对应方法名配合it描述具体场景与期望。对照真实用例 MenuCtr.test.ts可以看到这套结构如何落地测试只 Mock 了App.menuManager的 5 个方法refreshMenus、showContextMenu、rebuildAppMenu等并按refreshAppMenu/showContextMenu/setDevMenuVisibility等方法组织describe块每个it同时断言调用参数expect(mockShowContextMenu).toHaveBeenCalledWith(menuType, menuData)与返回值expect(result).toEqual({ shown: true })实现了“行为而非实现”的断言。Mock 外部依赖Mock 模块函数对普通依赖模块声明一个具名 mock 函数再交给vi.mock工厂const mockFunction vi.fn(); vi.mock(module-name, () ({ functionName: mockFunction, }));注意vi.mock会被 Vitest 自动提升hoist到文件顶部因此工厂函数中不能直接引用后定义的外部变量。仓库测试中普遍采用vi.hoisted解决该问题例如 ShellCommandCtr.test.ts 先声明const { ipcMainHandleMock } vi.hoisted(() ({ ipcMainHandleMock: vi.fn(), }));再在工厂函数里引用ipcMainHandleMock使 mock 既能被提升执行又能在测试体内读取与断言。Mock Node.js 核心模块控制器常调用child_process.exec等系统 API。原文档给出的方案是同时 Mockchild_process与util.promisify用同一个mockExecImpl串联两者保持promisify(exec)(cmd)的行为与真实调用链一致const mockExecImpl vi.fn(); vi.mock(child_process, () ({ exec: vi.fn((cmd, callback) { return mockExecImpl(cmd, callback); }), })); vi.mock(util, () ({ promisify: vi.fn((fn) { return async (cmd: string) { return new Promise((resolve, reject) { mockExecImpl(cmd, (error: Error | null, result: any) { if (error) reject(error); else resolve(result); }); }); }; }), }));这个模式的关键在于mock 的是模块边界而非内部实现——只要被测代码通过promisify(exec)拿结果你的mockExecImpl就能以(cmd, callback)形式接管且reject/resolve语义与真实 Promise 一致错误路径分支同样可测。仓库实践electron 全局 Mock 与 per-file 覆盖比逐文件手写 electron Mock 更进一步的是仓库的全局方案。setup.ts由vitest.config.mts的setupFiles在每个测试文件执行前加载做了三件事// Mock node-mac-permissions before any imports vi.mock(node-mac-permissions, () import(./node-mac-permissions)); // Default electron mock: gives every suite a ready app (paths readiness) vi.mock(electron, () import(./electron)); vi.mock(/utils/logger, () ({ createLogger: () ({ debug: vi.fn(), error: vi.fn(), info: vi.fn(), verbose: vi.fn(), warn: vi.fn() }), }));默认的 electron Mock 提供了完整的app对象getAppPath返回/mock/app、getPath返回/mock/{name}、whenReady立即 resolve 等以及BrowserWindow、ipcMain、Menu、shell、dialog等常用命名空间的轻量 stub。其设计意图源文件注释中明确说明是像/const/dir这类在导入时就访问app.getAppPath()/app.getPath(userData)的模块任何测试无需重复 stub 即可安全加载从而让生产代码可以继续使用值风格的路径常量。而测试文件自己声明的vi.mock(electron, …)会按文件优先级覆盖这个默认值。MenuCtr.test.ts 正是如此vi.mock(electron, () ({ BrowserWindow: { fromWebContents: fromWebContentsMock, }, ipcMain: { handle: ipcMainHandleMock, }, }));只取自己关心的BrowserWindow.fromWebContents与ipcMain.handle两个成员其余由用例内mockReturnValueOnce精确驱动。测试 IPC 事件处理器结合 IpcContext 的完整示例原文档给出的 IPC 测试示例验证了“入参 → 依赖调用 → 返回结构”三层断言it(should handle IPC event correctly, async () { mockSomething.mockReturnValue({ result: success }); const result await controller.ipcMethodName({ param1: value1, param2: value2, }); expect(result).toEqual({ success: true, data: { result: success }, }); expect(mockSomething).toHaveBeenCalledWith(value1, value2); });对照 MenuCtr.test.ts 中popupContextMenu用例可以看到当 IPC 方法需要调用方窗口时的更完整写法通过runWithIpcContext注入一个携带event.sender的IpcContext再断言BrowserWindow.fromWebContents收到了sender、menuManager.popupContextMenu收到了解析出的窗口对象it(should resolve the calling window via BrowserWindow.fromWebContents and delegate to menuManager, async () { const params { items: [{ id: copy, label: Copy, type: normal as const }] }; const sender {} as any; const context { event: { sender } as any, sender } as IpcContext; const mockWindow {} as any; fromWebContentsMock.mockReturnValueOnce(mockWindow); mockPopupContextMenu.mockResolvedValueOnce({ clickedId: copy }); const result await runWithIpcContext(context, () menuController.popupContextMenu(params), ); expect(fromWebContentsMock).toHaveBeenCalledWith(sender); expect(mockPopupContextMenu).toHaveBeenCalledWith(params, mockWindow); expect(result).toEqual({ clickedId: copy }); });同文件还补了一个边界用例无 IPC 上下文时fromWebContents不应被调用、window参数应为null。这正体现了下节“边界与错误路径全覆盖”的要求。面向真实复杂控制器的 Mock 深度仓库中 ShellCommandCtr.test.ts 展示了处理复杂控制器进程生命周期、平台能力探测时的进阶技巧值得在编写新测试时借鉴Mock 出具备 EventEmitter 语义的子进程对象被测的ShellProcessManager会注册并移除exit/error/close监听测试便用 Map 实现on/once/off再用emitChildProcess(event, ...args)手动触发事件使测试能跟随真实的进程退出时序如mockSpawn里把输出写入stdiofd、setTimeout后依次 emitexit与close能力探测的降级路径测试probeSandboxCapability抛错时视为“不可用”而非崩溃围栏构建失败createSandboxLaunchPlanreject会下调能力等级并携带原因而命令在可用沙箱内以非零退出则不触发降级——这两组断言把“失败归因”的边界划得非常精确安全边界断言如ensureSandboxWorkspace用例直接传入../../Windows/System32作为agentId断言路径仍被约束在 workspace 根目录内验证路径穿越防御。这些用例共同说明控制器测试的价值不在于“把依赖都 mock 掉”而在于通过受控的 mock 行为枚举出真实环境中才出现的失败形态并验证控制器对每种形态的响应。最佳实践清单原文档提出的五条准则结合仓库实际代码可以进一步具象化隔离测试beforeEach中先vi.clearAllMocks()再重建控制器如 MenuCtr.test.ts#L43-L46用mockReturnValueOnce/mockResolvedValueOnce提供一次性行为避免用例间相互污染全面覆盖同时覆盖正常流showContextMenu传 typedata、退化流无 IPC 上下文时 window 为null与错误处理不存在的shell_id返回success: false且error含not found见 ShellCommandCtr.test.ts#L546-L553命名清晰it描述用“should 行为 预期结果”句式如should call menuManager.showContextMenu with type and data让失败报告本身即文档避免测试实现细节断言控制器对外可观察的行为返回值结构、对menuManager的调用参数而非内部变量或私有方法Mock 全部外部依赖electron、node-mac-permissions、子进程、网络等一律通过vi.mock隔离优先依赖 全局 setup 提供的默认 electron/logger Mock仅在需要特定行为时按文件覆盖。小结LobeHub Desktop 的控制器测试体系可归纳为三层约定层__tests__同目录、文件名.test.ts、基础设施层vitest.config.mts的别名与 node 环境 setup.ts的全局 electron/logger Mock 按文件覆盖的vi.mock、用例层双层describe、行为断言、边界与错误路径枚举。新增控制器时参照 _template.ts 编写实现再按本文骨架与 MenuCtr.test.ts 范式补齐测试即可得到一套与主进程生命周期完全解耦、可在任意平台稳定运行的单元测试。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考