前端工程的端到端测试代码覆盖率收集方案

背景：Playwright 覆盖率方案的局限

Playwright 是当下最主流的端到端（E2E）测试框架之一，但其官方推荐的代码覆盖率收集方案存在一个根本性局限——它默认被测站点运行的是未经打包的原生 JavaScript。

对于经由 Vite、Webpack 等构建工具处理后的生产产物，Playwright 原生收集到的覆盖率数据难以映射回源代码，最终生成的报告无法准确反映真实的代码覆盖情况。

业界通行方案及其缺陷

目前较为常见的做法是直接在构建流程中集成 Istanbul.js 的插桩能力：在项目中配置插桩 → 运行 Playwright 用例 → 收集覆盖率数据 → 通过命令行工具生成报告。

然而，这一方案有两个前提条件，在实际工程中往往难以同时满足：

前提一：测试用例必须与前端工程同仓库。Istanbul.js 的覆盖率报告依赖本地源码进行符号解析，一旦 E2E 用例与前端工程分属不同代码仓库，报告便无从生成。

前提二：测试过程必须是自动化的。然而现实情况是，并非所有前端业务代码都能像成熟开源项目那样拥有规范的项目结构和完善的 CI/CD 流水线。许多企业内部的 UI 自动化平台，其 E2E 用例与前端工程天然是解耦分离的；更常见的情况是，团队完全依赖手工测试来保障代码质量，根本不存在自动化用例。

针对上述痛点，我们构建了 Canyon。

Canyon 的设计思路

Canyon 的核心能力建立在 Istanbul.js 成熟的 AST 插桩技术之上。在构建阶段，Istanbul.js 通过解析 JavaScript 语法树，在语句、函数、分支的起始位置注入计数器，从而精确记录代码在运行时的执行路径。

围绕”E2E 用例与前端工程分离”这一核心问题，Canyon 从两个维度给出了解法。

第一维度：源代码解绑

Canyon 定义了 buildHash 机制，并开发了配套的 @canyonjs/babel-plugin 插件。

在 CI 流水线阶段，插件自动侦测当前流水线的关键环境变量——repoID 与 CommitSHA——并将其哈希值写入覆盖率对象（coverage）中。这样，在后续的报告生成阶段，服务端便可凭借这组标识通过 GitLab API 拉取对应版本的源码，完成符号映射与报告渲染。

源代码不再需要与测试工程共存，这是 Canyon 与传统方案最本质的差异。

第二维度：分布式覆盖率收集

对于没有自动化用例、依赖手工测试的团队，覆盖率数据的来源是分散的——它们产生于不同测试人员的浏览器会话中，时间不一，环境各异。

Canyon 将覆盖率数据的收集架构设计为类分布式系统：

磁盘消息队列：缓冲并异步处理来自多个客户端的覆盖率上报，避免峰值流量造成数据丢失；
幂等消费：保证同一份数据重复上报时不会导致统计结果偏差；
分布式锁：在并发场景下确保覆盖率数据合并操作的原子性；

上述机制共同保障了覆盖率数据的实时性与准确性，使得报告能够在测试执行过程中动态更新。

此外，Canyon 还提供了快照（Snapshot）功能：可对指定的覆盖率 Tag 单独生成时间点快照。结合 Case ID 使用，测试人员可以精准还原某条具体测试用例执行后的代码覆盖状态，为缺陷定位和覆盖分析提供有力支撑。

Canyon 解决了什么问题

痛点	Canyon 的解法
打包后 JS 无法映射源码	Istanbul.js AST 插桩 + buildHash 源码解绑
E2E 用例与前端工程分离	服务端凭 repoID/CommitSHA 独立拉取源码
没有自动化用例，只有手工测试	分布式收集架构，支持多浏览器实例并发上报
覆盖率数据合并准确性	磁盘队列 + 幂等消费 + 分布式锁
单条 Case 的覆盖率溯源	快照功能，按 Case ID 定点生成报告

小结

Canyon 通过两个关键设计——构建时 buildHash 插桩与分布式覆盖率收集服务——将代码覆盖率的采集范围从”必须有自动化用例且用例与工程同仓库”这一苛刻前提，扩展到了几乎任何前端研发场景：无论是接入了 UI 自动化平台的团队，还是仍以手工测试为主的团队，都可以通过 Canyon 获得准确的、可追溯到源代码级别的覆盖率视图。

帮助测试人员发现尚未被触达的代码路径，正是 Canyon 的核心价值所在。