Excalidraw单元测试覆盖率现状与改进建议

Excalidraw 单元测试覆盖率现状与改进建议

在开源项目快速迭代的今天，一个看似“能用”的功能背后，真正决定其能否长期存活的，往往是那些看不见的工程基建——尤其是测试体系。Excalidraw 作为一款广受欢迎的手绘风格白板工具，凭借简洁交互和强大扩展性，在技术设计、远程协作等领域占据了独特位置。但随着 AI 生成、实时协同等复杂功能不断融入主干代码，项目的可维护性正面临严峻考验。

最直观的问题之一就是：我们到底有多确定新提交的代码不会破坏已有逻辑？答案很大程度上取决于单元测试的覆盖深度。目前 Excalidraw 的测试覆盖率虽有基础支撑，但在核心模块如图形状态管理、AI 指令解析和协作同步机制中仍显薄弱。这不仅增加了重构风险，也让社区贡献者在修改底层逻辑时缺乏信心。

我们测了什么？又漏了什么？

Excalidraw 基于 React 和 TypeScript 构建，整体架构清晰，分层明确。理想情况下，像element/、scene/这类处理图形数据的核心模块应当拥有接近 100% 的函数和分支覆盖率。然而实际报告显示，部分关键路径的行覆盖率甚至低于 60%，远未达到健康前端项目建议的80% 行覆盖 + 70% 分支覆盖标准（依据 Istanbul 工具链）。

以measureText函数为例，它是布局计算的基础组件：

import { measureText } from "../src/element/textElement"; describe("measureText", () => { it("should return correct dimensions for given text and font", () => { const result = measureText("Hello World", { fontSize: 16, fontFamily: "Virgil" }); expect(result.width).toBeGreaterThan(0); expect(result.height).toBe(16); }); it("should handle empty string correctly", () => { const result = measureText("", { fontSize: 16, fontFamily: "Virgil" }); expect(result.width).toBe(0); expect(result.height).toBe(16); }); });

这类纯函数逻辑简单、输入输出明确，非常适合写高覆盖率测试。问题不在于“能不能测”，而在于“是否强制要求必须测”。当前 CI 流程虽然运行 Jest 并生成报告，但并未设置阈值门禁——这意味着即使新增代码完全没有测试，也能顺利合并。长此以往，技术债只会越积越多。

更深层的问题是某些模块天生“难测”——比如 AI 图形生成功能。

AI 功能怎么测？别让“智能”成为逃避测试的理由

现在越来越多用户期望通过一句话就自动生成流程图或界面原型，Excalidraw 社区也在积极集成此类能力（如 excalidraw-ai）。但这类功能往往被当作“实验性特性”而忽略测试，理由通常是：“AI 输出不确定，没法断言”。

这个观点其实是个误解。我们不需要测试 AI 模型本身，而是要测试系统如何理解和使用 AI 的输出。

举个例子，假设有一个parseSketchPrompt函数负责将自然语言转为结构化指令：

import { parseSketchPrompt } from "../src/ai/promptParser"; describe("parseSketchPrompt", () => { it("should detect flowchart keywords and generate nodes", () => { const commands = parseSketchPrompt("Draw a flowchart with start, process, decision, end"); expect(commands.type).toBe("flowchart"); expect(commands.nodes).toContainEqual(expect.objectContaining({ type: "start" })); expect(commands.edges).toBeDefined(); }); it("should fallback gracefully on unknown input", () => { const commands = parseSketchPrompt("This makes no sense at all"); expect(commands.type).toBe("unknown"); expect(commands.nodes.length).toBe(0); }); });

只要约定好输出格式为 JSON 结构（哪怕内容由远程模型生成），前端就可以完全 mock 掉 AI 调用，专注于验证后续的图形创建逻辑是否正确执行。这才是合理的关注点分离：AI 负责“想”，程序负责“做”，而我们要确保“做的动作”始终可靠。

因此，解决 AI 难测问题的关键不是放弃测试，而是做好抽象：

• 定义清晰的中间表示（Intermediate Representation），如{ type: 'rectangle', x, y, metadata }；
• 将 AI 调用封装为独立服务接口，便于在测试中替换为固定响应；
• 对解析器、映射规则等内部逻辑进行全覆盖测试。

一旦完成这一步，AI 功能反而可以比传统手动操作更容易验证——毕竟人的输入更不可控。

实时协作的状态同步：高并发下的稳定性基石

如果说 AI 是锦上添花，那多人实时协作就是现代白板工具的刚需。Excalidraw 使用基于 WebSocket 的增量更新协议，配合自定义差分机制实现多端同步。这种场景下，最怕的就是“改着改着画面乱了”或者“别人删了我的元素”。

根本保障来自状态更新函数的确定性和幂等性。例如下面这个applyElementUpdate的测试用例：

import { applyElementUpdate } from "../src/scene/applyUpdates"; describe("applyElementUpdate", () => { const originalElement = { id: "rect1", type: "rectangle", x: 0, y: 0, width: 100, height: 50 }; it("should update position when receiving move action", () => { const update = { id: "rect1", x: 10, y: 20 }; const next = applyElementUpdate(originalElement, update); expect(next.x).toBe(10); expect(next.y).toBe(20); }); it("should not mutate original object", () => { const update = { width: 200 }; const next = applyElementUpdate(originalElement, update); expect(next).not.toBe(originalElement); // 不可变性 expect(originalElement.width).toBe(100); // 原对象未受影响 }); });

这类函数本质上是纯逻辑运算，非常适合单元测试，并且应该追求100% 分支覆盖率。因为任何遗漏都可能导致客户端之间出现状态漂移，最终导致协作失败。

现实中，这类逻辑常常散落在事件处理器或副作用钩子中，导致难以独立测试。改进方向很明确：
把状态变更逻辑从“响应式回调”中剥离出来，变成可独立调用的纯函数。这样不仅能提升可测性，还能增强复用性和调试体验。

如何推动改变？从文化到机制的全方位升级

测试覆盖率低从来不只是技术问题，更是工程文化和流程设计的结果。Excalidraw 作为一个活跃的开源项目，完全有能力建立起更严格的工程质量防线。以下几点建议值得考虑：

1. 设置覆盖率阈值门禁

在jest.config.js中启用coverageThreshold，防止覆盖率进一步下滑：

module.exports = { coverageThreshold: { global: { branches: 70, functions: 80, lines: 80, statements: 80, }, }, };

CI 在 PR 提交时自动检查，若低于阈值则阻止合并。这不是为了惩罚贡献者，而是建立共同的质量底线。

2. 强化模块边界，支持独立测试

当前代码库耦合度偏高，建议逐步拆分为子包：
-@excalidraw/core：核心元素与状态管理
-@excalidraw/ai：AI 相关解析与适配
-@excalidraw/collab：协作同步协议实现

每个子包可独立发布版本、运行测试、设定覆盖率目标，极大提升可维护性。

3. 改进文档与引导机制

在CONTRIBUTING.md中加入明确指引：

“新增功能或修改核心逻辑时，请务必提供相应的单元测试。优先采用 TDD 方式编写代码。”

同时可在 PR 模板中添加 checklist：
- [ ] 新增测试用例
- [ ] 覆盖边界情况
- [ ] 不降低整体覆盖率

4. 避免快照测试滥用

Jest 的快照测试虽方便，但极易导致“只关心输出不变，不管逻辑对错”。对于复杂的对象结构（如元素树），应优先使用结构化断言而非.toMatchSnapshot()，避免掩盖潜在问题。

5. 引入奖励机制

对于补全关键模块测试、显著提升覆盖率的贡献者，可通过 README 致谢、Discord 特殊身份组等方式给予认可，激励社区共建测试生态。

写在最后：测试不是负担，而是自由的前提

很多人觉得“写测试拖慢开发速度”，但经验告诉我们恰恰相反：良好的测试覆盖率才是快速迭代的底气。当你知道每一个底层函数都被充分验证过，你才敢放心地重构、优化、引入新技术。

Excalidraw 已经走过了从创意到产品的关键阶段，下一步的目标应该是成为值得企业级信赖的协作基础设施。而这离不开扎实的工程实践支撑。

提高单元测试覆盖率，不只是为了数字好看，更是为了让每一位开发者都能在这个项目上“安全地创新”。当测试成为习惯而非负担，这个开源生态才能真正走向成熟。

那种“随便改几行也不怕出事”的从容感，才是高质量代码的最大回报。