cal.diy 测试 Mock 实现模式指南：以 Calendar 接口为核心，构建稳定、类型安全的日历服务与 App-Store 测试

cal.diy 测试 Mock 实现模式指南：以 Calendar 接口为核心，构建稳定、类型安全的日历服务与 App-Store 测试

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy

本篇技术指南基于 cal.diy（开源调度基础设施）仓库的工程规范文档 agents/rules/testing-mocking.md，系统讲解测试文件中日历服务与 App-Store 集成资源的 Mock 实现模式：为什么 Mock 必须实现统一的Calendar接口、为什么应当避免mockDeep深拷贝式 Mock、以及在类型冲突难以解决时如何优雅退化为手写 Fake 实现。读完本文，你将掌握一套可直接应用于本项目测试代码的可维护 Mock 范式，从根本上降低由 Mock 引起的测试脆弱性与假阳性风险。

背景：差的 Mock 是"脆弱测试"与"假阳性"的根源

该规则文档在 Frontmatter 中明确声明了其影响等级与原因：

• impact: MEDIUM
• impactDescription: Poor mocks cause flaky tests and false positives（糟糕的 Mock 会导致测试不稳定与假阳性）

结合仓库的测试实践可以理解这一论断的深层原因：cal.diy 的测试大量使用 Vitest 的vi.mock来替换第三方日历服务、App-Store 应用模块等重型依赖。如果 Mock 只是"从具体服务类型上零散复制几个属性"，那么一旦真实服务的类结构变化（新增方法、改变返回类型、调整私有字段），Mock 就会与类型系统脱节，出现两类典型症状：

1. 类型兼容性问题：Mock 对象与消费方期望的接口类型不符，编译阶段（tsc）报错，导致测试代码无法推进；
2. 运行时假阳性：Mock 只覆盖了部分方法，被测代码走到未 Mock 的分支时静默拿到错误结果或抛异常，测试"看起来绿了"，实际却根本没有验证目标行为。

因此，该规则给出的核心方法论可以概括为一句话：Mock 的形态应追随被测代码所依赖的"契约"（接口），而非追随某个具体实现类的内部形状。

认识被测主体：日历服务与Calendar接口

在理解 Mock 规则之前，需要先了解生产代码中日历服务的组织方式，因为 Mock 规则正是为贴合这一结构而设计的。

所有日历服务统一实现Calendar接口

Calendar接口定义在 packages/types/Calendar.d.ts（Calendar.d.ts中interface Calendar，第 294 行起）。它规定了日历服务必须提供的完整方法集合：

在具体实现层，所有日历服务都严格实现该接口，例如：

• packages/app-store/feishucalendar/lib/CalendarService.ts 第 35 行：class FeishuCalendarService implements Calendar，随后通过构造函数接收CredentialPayload完成鉴权与初始化；
• packages/lib/CalendarService.ts 第 388 行：抽象基类BaseCalendarService implements Calendar，被 CalDAV、Exchange 等多项服务复用。

日历服务以"映射表 + 动态导入"的方式注册

具体服务不会在调用方被直接实例化。生成的注册表 packages/app-store/calendar.services.generated.ts 定义了一个CalendarServiceMap，把日历类型字符串映射到动态 import返回的模块 Promise：

export const CalendarServiceMap = process.env.NEXT_PUBLIC_IS_E2E === "1" ? {} : { applecalendar: import("./applecalendar/lib/CalendarService"), feishucalendar: import("./feishucalendar/lib/CalendarService"), googlecalendar: import("./googlecalendar/lib/CalendarService"), // ... 其余日历类型 };

而运行时工厂 packages/app-store/_utils/getCalendar.ts 的getCalendar()会从该映射表中按凭据的type字段取出对应的导入函数、执行calendarApp.default得到构造器并创建实例，最终统一返回类型为Calendar | null的服务对象。

由此可以理解规则文档第一段"Since all calendar services implement theCalendarinterface and are stored in a map"（所有日历服务都实现了Calendar接口并被存储在映射表中）所描述的架构事实：消费方只依赖接口与映射表，从不直接依赖某个具体日历类。Mock 若破坏这一约定，就等于把映射表机制替换成了一套与生产形态无关的假结构。

Calendar Service Mocks：实现整个Calendar接口，而非逐属性复制

规则文档的核心指令非常明确：

When mocking calendar services in Cal.diy test files, implement theCalendarinterface rather than adding individual properties from each specific calendar service type (likeFeishuCalendarService).

即：测试文件中 Mock 日历服务时，应当实现完整的Calendar接口，而不是从某个具体日历服务类型（如FeishuCalendarService）上逐个复制属性。

推荐做法：Mock 工厂返回满足接口形状的完整对象

仓库中 packages/features/calendars/lib/getCalendarsEvents.test.ts 是该模式的教科书式范例。它通过vi.mock("@calcom/app-store/calendar.services.generated")在测试层替换掉生成的映射表，并为每个日历 key 提供 Promise 化的 Mock 模块：

const mockGoogleGetAvailability = vi.fn().mockResolvedValue([]); const mockGoogleGetAvailabilityWithTimeZones = vi.fn().mockResolvedValue([]); vi.mock("@calcom/app-store/calendar.services.generated", () => { return { CalendarServiceMap: { googlecalendar: Promise.resolve({ default: (credential: { id: number }) => ({ getCredentialId: () => credential.id, createEvent: vi.fn().mockResolvedValue({}), updateEvent: vi.fn().mockResolvedValue({}), deleteEvent: vi.fn().mockResolvedValue({}), getAvailability: mockGoogleGetAvailability, getAvailabilityWithTimeZones: mockGoogleGetAvailabilityWithTimeZones, listCalendars: vi.fn().mockResolvedValue([]), }), }), office365calendar: Promise.resolve({ default: (credential: { id: number }) => ({ // 同样的完整方法集合…… }), }), }, }; });

这段 Mock 的形态与生产结构严格对应：

• 模块边界一致：Mock 的是CalendarServiceMap所在的生成模块（与 getCalendar.ts 的 import 源一致）；
• 导入结构一致：每个 key 的值是Promise.resolve({ default: factory })，与动态import()产生的模块形状相同；
• 返回对象与接口一致：工厂返回的对象拥有getCredentialId / createEvent / updateEvent / deleteEvent / getAvailability / getAvailabilityWithTimeZones / listCalendars，恰好对应Calendar接口的全部（非可选）成员。

正因返回对象完整实现了接口，无论后续是直接调用getAvailability、createEvent还是被getCalendar工厂消费，被测代码都能以类型安全的方式工作；而getAvailability等关键方法被提取为可复用的vi.fn()变量（如mockGoogleGetAvailability），便于在每个用例中单独改写返回值——这正是"既类型安全又可控"的 Mock 设计。

反面做法：从具体类型零散拼属性为什么危险

反例是文档点名批评的做法：Mock 时"照抄"某个具体服务（如FeishuCalendarService）中用到的一两个属性，而不是面向接口补齐契约。假设代码逻辑依赖feishucalendar的某一个私有辅助字段，测试 Mock 就照抄该字段、跳过其余方法，这会带来三个问题：

1. 类型兼容性崩塌：消费方（例如被 Mock 的对象会流入一个接收Calendar参数的函数）期望整个接口，Mock 却缺少updateEvent、deleteEvent等方法，tsc直接报错，最终只能靠as断言强行"捂住"类型错误，让测试失去类型保障；
2. 与映射表机制脱节：生产代码通过CalendarServiceMap动态加载服务，Mock 若绕开该结构、单独实例化具体类，就无法复现真实的加载路径，测试覆盖到的是"假接线"，而不是真实调用链；
3. 重构脆弱性：具体服务类的内部属性属于实现细节、最易变动，Mock 依赖实现细节越多，服务端重构时测试越先崩。

E2E/集成环境下的特例说明

值得注意，映射表在NEXT_PUBLIC_IS_E2E === "1"时本身会被生成为空对象{}（见 calendar.services.generated.ts），说明在 Playwright E2E 场景中日历服务会被整体禁用。这也是为什么 Mock 方案要统一收敛在接口层——不同测试层级可以各取所需，但契约保持一致。

App-Store Integration Mocks：用简单、直接的接口 Mock 取代mockDeep

规则文档的第二条指令针对 App-Store 集成测试：

When mocking app-store resources in Cal.diy tests, prefer implementing simpler mock designs that directly implement the required interfaces rather than trying to match complex deep mock structures created withmockDeep.

即：测试中 Mock App-Store 资源时，优先采用"直接实现所需接口"的简单设计，而不是费力去复刻mockDeep生成的深层 Mock 结构。

mockDeep的适用场景与问题根源

mockDeep来自vitest-mock-extended，能递归地把一个复杂对象的每一层都变成vi.fn()。仓库中确实存在合理使用它的场景，例如 packages/features/calendars/lib/mocks/CalendarManager.ts：

import { mockReset, mockDeep } from "vitest-mock-extended"; import { CalendarManager } from "../CalendarManager"; const CalendarManagerMock = mockDeep<typeof CalendarManager>();

当被测目标本身是一个"大而全"的管理器类（如聚合多个日历操作的CalendarManager）时，mockDeep可以快速产出完整 Mock。但它的代价是：Mock 的结构深度与类型体操显著复杂。当模块之间存在循环依赖、联合类型、泛型或品牌类型时，mockDeep<T>的推断极易产生类型兼容性冲突——这正是规则文档所说 "complex deep mock structures" 与 "type compatibility issues" 的由来。

而对大多数 App-Store 集成测试来说，被测代码真正调用的往往只是某个应用卡片组件、工具函数或服务的少量公开方法。为了一两个方法引入整棵深拷贝 Mock 树，属于不必要的复杂度：既难维护，也容易在服务接口微调时"牵一发而动全身"。

推荐做法：手写返回所需接口的轻量 Fake

更优的方案是像getCalendarsEvents.test.ts那样，直接用普通对象 +vi.fn()组装出"恰好满足被测代码所需接口"的轻量 Fake。这类设计的特点：

• 只声明被测代码实际调用的方法，其余方法可省略（前提是消费方类型允许）；
• 方法返回值显式可控，测试意图一目了然；
• 不依赖vitest-mock-extended的深层推断，绕开类型兼容性雷区；
• 易于重构，改一个方法签名只影响一处。

大规模自动化 Mock 场景：Proxy 化映射表

当测试需要同时覆盖大量日历/视频服务、又不想为每个服务手写 Mock 时，仓库给出了一个"创造性的简单方案"——见测试基建 packages/testing/src/lib/bookingScenario/bookingScenario.ts 第 52-70 行。它以Proxy包装CalendarServiceMap，任何 key 被访问时都自动返回一个标准化的 Mock 构造器：

// 共享的 Mock 日历构造器集合：vi.mock 工厂与 mockCalendar 都可访问 const calendarServiceConstructorMocks: Record<string, ReturnType<typeof vi.fn>> = {}; function getOrCreateCalendarServiceMock(key: string): ReturnType<typeof vi.fn> { if (!calendarServiceConstructorMocks[key]) { calendarServiceConstructorMocks[key] = vi.fn(); } return calendarServiceConstructorMocks[key]; } vi.mock("@calcom/app-store/calendar.services.generated", () => ({ CalendarServiceMap: new Proxy({} as Record<string, Promise<{ default: ReturnType<typeof vi.fn> }>>, { get(_target, prop: string) { if (typeof prop === "symbol") return undefined; return Promise.resolve({ default: getOrCreateCalendarServiceMock(prop) }); }, }), }));

这段代码同时示范了规则文档的三条通用指导：

• 按需惰性 Mock：Proxy的get钩子保证"用到哪个服务才 Mock 哪个服务"，测试只会为实际触碰的日历类型创建构造器，避免真实模块（如 feishu/lark）被 import 进测试进程——注释明确指出这能阻止工作进程关闭阶段触发额外的异步 fetch 调用；
• 模块形状与接口保持简单：每个 key 仍返回Promise.resolve({ default: mock })这一统一结构，与生产动态 import 的模块形状、与CalendarServiceMap的消费方式完全一致；
• 共享可变状态被显式管理：构造器 Mock 集中在模块级 Map 中，供vi.mock工厂与测试辅助函数共同读写。

General Guidance：三条可落地的工程准则

规则文档的第三部分给出三条操作性极强的通用建议，它们在仓库中都有对应实践，逐一展开如下。

1. 复杂 Mock 遇到类型问题时，退化为简单 Fake 实现

For complex mocks that cause type compatibility issues with deep mocks, consider using simpler fake implementations.

"简单 Fake"不是妥协，而是一种主动的设计选择：当mockDeep等工具与模块类型产生不可调和的冲突时，一个手写的、只实现被测路径所需接口的 Fake 对象，往往比在类型体操里挣扎更快、更稳。判断标准是被测代码真正依赖的最小接口面——面向最小接口写 Fake，既能通过类型检查，也天然聚焦测试意图。

2. 必要时允许修改其他 Mock 文件以支持当前实现

When needed, you can modify other mock files to support your implementation.

Mock 之间常有共享依赖（例如全局prismaMock、通用模块 Mock）。当一个用例的 Mock 需要其他 Mock 的配合才能成立时，规则明确允许修改配套 Mock 文件。仓库中同样能看到这种"配套 Mock 协同"的实践，例如：

• packages/testing/src/lib/bookingScenario/bookingScenario.ts 同时vi.mock了calendar.services.generated、video.adapters.generated与@calcom/lib/crypto（用importOriginal保留真实实现、只包装加解密函数），多个 Mock 协同构造完整场景；
• getCalendarsEvents.test.ts开头先vi.mock("@calcom/lib/crypto", () => ({ symmetricDecrypt: vi.fn() }))，再借助vi.mocked(symmetricDecrypt)在用例内灵活编排返回值。

这一准则是"重构自由"的体现：当标准 Mock 成为实现目标的阻碍时，调整共享 Mock 的形态以服务整体测试设计是正当行为。

3. 标准 Mock 引发持续性类型错误时，鼓励创造性重构

Creative solutions and refactoring to better designs are encouraged when standard mocking causes persistent type errors.

最深层的一条原则：如果 Mock 代码反复出现类型错误，往往不是 Mock 写法的问题，而是被测代码的抽象边界本身值得重新审视。此时鼓励向上游重构——调整接口划分、收敛依赖、让生产代码消费更小的接口面——从而让测试自然变得简单。这条建议把 Mock 问题从"测试层的修补"提升到了"设计层的改进"，避免用层层as断言去掩盖架构债。

落地自检清单

在 cal.diy 仓库中新增或修改测试 Mock 时，可对照以下清单进行 Review（对应 CI 中 TypeScript 检查与测试稳定性的常见失败点）：

1. Mock 日历服务时，返回对象是否完整实现Calendar接口（而非从FeishuCalendarService等具体类复制属性）？
2. Mock App-Store 资源时，是否采用了直接实现所需接口的简单对象，而非盲目堆叠mockDeep？
3. Mock 的模块路径与导出形状是否与生产加载链一致（如CalendarServiceMap的Promise<{ default }>结构）？
4. 是否避免用as断言强行掩盖 Mock 与接口之间的类型缺口？
5. 当类型冲突持续存在时，是否考虑过简化 Fake、调整配套 Mock、甚至重构被测抽象，而不是继续在原有方案上加补丁？

遵循以上模式，Mock 才能真正成为稳定的测试地基，而非"脆弱测试与假阳性"的来源——这正是 agents/rules/testing-mocking.md 希望每一位仓库贡献者内化的工程共识。更完整的 Mock 设计规范可进一步参考 agents/rules/testing-incremental.md 与 agents/rules/testing-mocking.md 同目录下的其他测试规则，以及测试基建入口 packages/testing/src/lib/bookingScenario/bookingScenario.ts。

【免费下载链接】cal.diyScheduling infrastructure for absolutely everyone.项目地址: https://gitcode.com/GitHub_Trending/ca/cal.diy