Mapbox GL JS 单元测试中解决 TextDecoder 未定义问题

问题背景

在使用 Mapbox GL JS 3.0.1 版本进行前端开发时，开发者在编写 Jest 单元测试时遇到了一个常见问题：任何导入 mapbox-gl 模块的测试文件都会抛出"TextDecoder is not defined"的错误。这个问题通常出现在使用 jsdom 环境的测试场景中。

问题分析

TextDecoder 是现代浏览器提供的 API，用于将字节流解码为字符串。Mapbox GL JS 内部可能使用了这个 API 来处理某些数据。然而，在 Jest 测试环境中，虽然 jsdom 模拟了浏览器环境，但它并没有完整实现所有的 Web API，TextDecoder 就是其中之一未被完全实现的功能。

解决方案

要解决这个问题，我们需要在 Jest 测试环境中手动提供 TextDecoder 和 TextEncoder 的实现。Node.js 的 util 模块中已经包含了这些功能的实现，我们可以直接使用：

import * as util from 'util';

// 在 Jest 的 setup 文件中添加以下代码
Object.defineProperty(window, 'TextEncoder', {
  writable: true,
  value: util.TextEncoder
});

Object.defineProperty(window, 'TextDecoder', {
  writable: true,
  value: util.TextDecoder
});

实现细节

1. util 模块：Node.js 内置的 util 模块提供了 TextEncoder 和 TextDecoder 的实现，这与浏览器中的实现功能相同。

2. Object.defineProperty：我们使用这个方法将这些实现添加到全局 window 对象上，模拟浏览器环境。

3. writable: true：这个配置允许在测试过程中如果需要可以重新定义这些属性。

最佳实践

1. 将上述代码添加到 Jest 的 setup 文件中（通常是 setupTests.js 或类似的配置文件）。

2. 确保在所有测试运行之前这段代码已经执行。

3. 如果项目中有多个测试文件需要这些 polyfill，集中管理比在每个测试文件中单独添加更高效。

扩展思考

这个问题不仅限于 Mapbox GL JS，任何在测试环境中使用现代浏览器 API 的库都可能遇到类似问题。理解如何在测试环境中模拟浏览器特定的功能是前端测试开发的重要技能。对于其他缺失的浏览器 API，也可以采用类似的 polyfill 方法来解决测试环境中的兼容性问题。

通过这种方式，我们不仅解决了 Mapbox GL JS 的测试问题，也为项目中可能遇到的其他类似浏览器 API 缺失问题提供了解决思路。