ES-Toolkit 项目构建输出测试方案探讨

构建输出测试的重要性

在 JavaScript/TypeScript 库开发中，构建过程将源代码转换为最终发布的包是一个关键环节。ES-Toolkit 项目目前面临一个常见但重要的问题：如何确保构建输出(dist)的正确性。这个问题之所以重要，是因为：

1. 构建过程可能引入错误：从 TypeScript 到 JavaScript 的转换、模块系统的转换(ESM/CJS)、代码压缩等步骤都可能意外改变代码行为
2. 测试环境与实际使用环境差异：当前测试直接针对源代码，无法发现构建后特有的问题
3. 模块兼容性问题：需要确保 ESM 和 CJS 两种模块系统都能正常工作

现有测试体系的局限性

ES-Toolkit 目前的测试配置存在以下特点：

1. 测试直接针对源代码：通过 package.json 的 exports 字段将导入解析到 src 目录下的 TypeScript 文件
2. 两种导入方式并存：
   • 无扩展名的相对导入：import { x } from './x'
   • 带扩展名的相对导入：import { x } from './x.ts'
3. 基准测试(benchmark)通过包名导入，但被解析到源代码

这种配置导致无法验证构建后的输出是否正常工作，可能掩盖以下问题：

• 构建过程中遗漏了某些文件或函数
• 模块评估时的运行时错误
• 转译引入的细微错误

可行的解决方案分析

方案一：复用现有测试，强制解析到构建输出

实现思路： 通过修改 Vitest 配置，使用别名机制将导入重定向到 dist 目录下的构建输出。可以设置环境变量(TEST_LIB_EXT)来控制测试的是 ESM 还是 CJS 构建。

优点：

• 充分利用现有测试用例
• 实现相对简单

缺点：

• 需要运行所有测试两次(ESM 和 CJS)
• 测试成本较高
• 需要统一测试中的导入方式

方案二：集成测试方案

实现步骤：

1. 使用 yarn pack 打包库(自动触发 prepack 构建 dist)
2. 创建一个测试工作区，将打包结果作为依赖
3. 编写专门的集成测试用例

优点：

• 更接近真实使用场景
• 可以针对性地测试关键功能
• 不需要运行全部单元测试

缺点：

• 需要额外设置测试环境
• 需要编写新的测试用例

补充建议：类型检查工具

除了上述方案，还可以在 CI 中引入 @arethetypeswrong/cli 工具来检查构建输出的类型声明是否正确。这个工具可以检测类型声明文件中的常见问题，如：

• 错误的模块类型标记
• 类型声明与实现不匹配
• 模块解析问题

实施建议

对于 ES-Toolkit 项目，建议采用渐进式改进策略：

1. 首先引入基本的构建输出验证：

   • 添加 @arethetypeswrong/cli 检查
   • 编写少量关键功能的集成测试

2. 逐步完善测试覆盖：

   • 根据需要增加更多集成测试用例
   • 考虑对核心功能实施方案一的全面测试

3. 统一项目中的导入方式：

   • 规范化测试中的导入路径
   • 考虑使用一致的扩展名策略

这种方案可以在保证构建质量的同时，避免过度的测试负担，适合项目当前的开发阶段。