Excalidraw测试用例编写：单元测试与E2E覆盖
在现代前端工程中，一个功能丰富、交互复杂的Web应用若缺乏健全的测试体系，就如同在流沙上盖楼——看似光鲜，实则隐患重重。Excalidraw 作为一款广受欢迎的开源手绘风格白板工具，不仅支持自由绘图和实时协作，近年来还集成了AI生成功能，进一步提升了内容创建效率。随着功能迭代加速，如何确保每一次代码提交都不会破坏已有逻辑，成为开发团队面临的核心挑战。
这个问题的答案不在代码量的多寡，而在于测试策略的设计深度。尤其对于以用户交互为核心的可视化工具而言，单纯依赖人工验证显然不可持续。我们需要一套分层、可自动化、贴近真实使用场景的测试机制，来守护产品质量的生命线。
单元测试：构建稳定的底层逻辑基石
当我们在 Excalidraw 中拖拽一个矩形或输入一段文字时，背后其实是一系列纯函数在默默工作：坐标计算、ID生成、文本测量、数据结构转换……这些模块不依赖DOM，也不涉及网络请求，正是单元测试的最佳战场。
以generateId()函数为例，它是整个图形系统的基础组件之一。每个元素都需要唯一标识符，否则在协作环境中极易引发状态冲突。我们来看一段典型的测试实现：
import { generateId } from '../src/utils'; describe('generateId', () => { it('should return a string of length 10', () => { const id = generateId(); expect(typeof id).toBe('string'); expect(id.length).toBe(10); }); it('should generate different IDs on each call', () => { const id1 = generateId(); const id2 = generateId(); expect(id1).not.toBe(id2); }); });这段测试虽短，却揭示了单元测试的本质价值：快速反馈 + 精准定位。它运行在 Node.js 环境下，无需启动浏览器，毫秒级完成执行。更重要的是，一旦这个函数在未来被重构（比如改为使用 nanoid），只要行为不变，测试仍能通过；若有偏差，则立即报警。
但这里有个关键原则容易被忽视：不要测试实现细节，而是测试公共接口的行为。例如，你不该断言“ID是由 Math.random() 生成的”，因为这属于内部实现，随时可能变更。你应该关心的是：“输出是否满足长度和唯一性要求？”这才是真正的契约。
另一个常见误区是过度 mock。比如在测试 AI 指令解析逻辑时，有人会把整个 fetch 调用都 mock 掉，甚至连 JSON 解析也 mock。这种做法会让测试变得脆弱且脱离实际。正确的做法是只 mock 外部服务调用，保留核心数据处理流程的真实执行路径。
说到 AI 功能，其前端逻辑同样适合单元测试覆盖。以下是一个典型示例：
import { generateDiagramFromPrompt } from '../../src/ai/promptHandler'; import * as apiClient from '../../src/ai/apiClient'; jest.mock('../../src/ai/apiClient'); test('generates diagram elements from valid prompt', async () => { const mockResponse = { elements: [ { type: 'rectangle', x: 100, y: 100, width: 80, height: 40, text: 'Frontend' }, { type: 'rectangle', x: 100, y: 200, width: 80, height: 40, text: 'API Server' }, { type: 'rectangle', x: 100, y: 300, width: 80, height: 40, text: 'Database' }, { type: 'arrow', start: [140, 140], end: [140, 200] }, { type: 'arrow', start: [140, 240], end: [140, 300] } ] }; apiClient.fetchDiagram.mockResolvedValue(mockResponse); const result = await generateDiagramFromPrompt("Three-tier architecture: frontend, API, DB"); expect(result.elements).toHaveLength(5); expect(result.elements[0].text).toBe('Frontend'); expect(apiClient.fetchDiagram).toHaveBeenCalledWith("Three-tier architecture: frontend, API, DB"); });这个测试的重点不是“AI模型是否聪明”，而是“前端能否正确构造请求、解析响应并传递给渲染层”。即使后端暂时不可用，只要接口契约稳定，前端就可以独立推进开发与验证。
此外，对于一些涉及复杂算法的功能，如文本自动换行、字体宽度测量等，单元测试更是不可或缺。曾有一次，团队优化了国际化字符的支持，但未覆盖中文文本宽度计算：
test('measures Chinese text width correctly', () => { const width = measureText('你好世界', '16px Sans-serif'); expect(width).toBeGreaterThan(60); });正是这条简单的测试，在CI阶段捕获了一个潜在的布局溢出问题，避免了上线后画布错乱的风险。
端到端测试：还原真实用户的完整旅程
如果说单元测试是显微镜下的精细检查，那么端到端测试就是全景摄像机，记录用户从打开页面到完成目标的全过程。在 Excalidraw 中，这类场景比比皆是：新建画布 → 绘制图形 → 添加注释 → 使用AI生成架构图 → 分享链接给协作者。
这类流程跨越多个组件、多个异步操作，甚至涉及 WebSocket 实时通信，仅靠单元测试无法有效覆盖。这时就需要 Playwright 或 Cypress 这样的工具登场。它们能操控真实浏览器，模拟鼠标点击、键盘输入、拖拽动作，并等待UI状态更新。
下面是一个使用 Playwright 编写的典型E2E测试：
const { test, expect } = require('@playwright/test'); test.describe('Excalidraw Drawing Workflow', () => { test.beforeEach(async ({ page }) => { await page.goto('https://excalidraw.com'); await expect(page.locator('#canvas')).toBeVisible(); }); test('can draw a rectangle and add text', async ({ page }) => { // 选择矩形工具 await page.click('[aria-label="Rectangle"]'); // 在画布上绘制（模拟鼠标按下+移动+释放） await page.mouse.move(100, 100); await page.mouse.down(); await page.mouse.move(200, 200); await page.mouse.up(); // 插入文本 await page.click('[aria-label="Text"]'); await page.click(150, 250); await page.keyboard.type('Hello Excalidraw'); // 断言文本已成功插入 await expect(page.locator('.textElement').first()).toHaveText('Hello Excalidraw'); }); });这段代码的价值在于它验证了集成链路的完整性。它不仅能发现按钮点击无响应的问题，还能捕捉诸如“异步加载延迟导致操作失败”、“Canvas上下文未正确初始化”等跨层错误。
不过，E2E测试也有它的“性格缺陷”：脆弱且昂贵。一次UI类名的调整就可能导致几十个用例集体崩溃。因此，最佳实践是在关键节点添加专用的选择器属性：
<button>await page.click('[data-testid="tool-text"]');这样即使视觉样式改变，只要功能不变，测试就不会断裂。
另外，异步等待是E2E中最常见的陷阱。很多失败并非功能有问题，而是测试代码没有正确处理加载状态。Playwright 提供了智能等待机制，推荐使用expect(locator).toBeVisible()而非硬编码sleep(2000)。前者会主动轮询直到条件满足或超时，更加健壮。
为了提升效率，还可以将E2E测试拆分为多个独立描述块，便于并行执行和故障隔离。例如：
test.describe('AI Diagram Generation', () => { ... }); test.describe('Collaboration Sync', () => { ... }); test.describe('Export & Share', () => { ... });在CI环境中，这些套件可以分别运行在不同浏览器（Chromium、Firefox、WebKit）上，全面检验兼容性。
测试体系如何融入整体架构与工作流
Excalidraw 的测试并非孤立存在，而是深深嵌入其技术架构与研发流程之中。我们可以将其视为一个分层防护网：
[ 用户层 ] ↓ [ UI 层 ] ←---------------------→ [ 实时协作 WebSocket ] ↓ ↑ [ 业务逻辑层 ] —→ [ AI服务接口] ↓ [ 数据模型层 ] ←→ [ LocalStorage / IndexedDB ] ↓ [ 测试层 ] ├── 单元测试（Jest + React Testing Library） ├── 组件测试（Testing Library + Vitest） └── 端到端测试（Playwright / Cypress）每一层都有对应的测试策略：
-数据模型层：单元测试验证元素增删改查的逻辑；
-业务逻辑层：测试状态管理 reducer 和事件处理器；
-UI层：组件测试确保不同 props 下的渲染一致性；
-全链路：E2E测试贯穿前后端，模拟真实用户旅程。
在日常开发中，这套体系表现为一条清晰的工作流：
- 本地开发阶段：开发者编写功能的同时，同步补充单元测试。借助
vitest --watch模式，保存即运行，即时获得反馈。 - 提交前拦截：通过 Git Hook 自动触发 lint 和测试，覆盖率低于阈值（如85%）则拒绝提交，强制形成习惯。
- CI流水线执行：GitHub Actions 拉起 Playwright 容器，运行E2E测试，生成视频录制和截图，便于排查失败原因。
- 发布前冒烟测试：在预发布环境运行核心路径验证，确认“新建 → 绘图 → 保存 → 分享”流程畅通无阻。
这套机制曾多次化解重大风险。例如某次重构中，修改了手绘风格（sketchiness）参数的传递方式，导致部分设备上线条渲染异常。由于有组件测试断言 CanvasRenderingContext2D 的调用参数，问题在CI阶段就被捕获，避免流入生产环境。
还有一个经典案例是多人协作状态同步问题。两个用户同时编辑同一画布时，偶尔会出现元素位置错位。通过E2E测试模拟双客户端连接，并监听WebSocket消息广播顺序与内容，最终定位到序列化过程中的时间戳精度丢失问题。
设计考量与长期演进
在实践中我们总结出几条关键经验：
- 坚持测试金字塔模型：70%单元测试 + 20%组件测试 + 10%E2E测试。过多的E2E会导致维护成本飙升，过少则难以保障集成质量。
- 重视选择器稳定性：避免依赖CSS类名或DOM层级路径，统一使用
data-testid。 - 环境隔离：E2E测试使用专用账号与存储空间，防止污染真实用户数据。
- 性能优化：对耗时较长的AI相关测试标记为
@slow或按需运行，避免拖慢主流程。 - 引入视觉回归测试：结合 Percy 或 Chromatic 对关键页面进行截图比对，检测手绘风格渲染偏移。
更进一步，随着AI功能的深入，我们开始探索提示工程（prompt engineering）的可测试性。建立典型输入输出对的测试集，不仅能验证当前模型表现，也为未来模型升级提供回归基准。
开源社区也因此受益。贡献者提交PR时，自动化测试会立即反馈结果，无需维护者手动验证。这大大降低了参与门槛，提高了协作效率。
写在最后
一个好的测试体系，从来不是为了“应付流程”，而是为了让团队敢于创新。在 Excalidraw 的演进过程中，正是这套立体化的测试防护网，支撑着一次次大胆的功能尝试——无论是引入AI绘图，还是优化协作同步机制。
它让开发者有信心说：“这次改动不会破坏已有功能。”
也让用户可以安心地将每一次灵感记录下来，而不必担心数据丢失或协作混乱。
归根结底，测试的意义不只是“发现问题”，更是为创造力保驾护航。在一个鼓励快速迭代的时代，唯有扎实的质量保障，才能让创新走得更远。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
