使用Create React App+Jest测试时如何解决TextDecoder未定义的ReferenceError？

我尝试运行下面的测试用例，但抛出了TextDecoder is not defined错误。禁用这个测试后，其他所有测试都能正常运行。

测试代码 #

describe('getFirebaseStorageAvailableNames', () => {
  it('should return "1" when the array is empty', () => {
    const arr: string[] = [];
    expect(getFirebaseStorageAvailableNames(arr)).toBe('1');
  });

  it('should return the smallest available number as a string', () => {
    const arr: string[] = ['1', '2', '3'];
    expect(getFirebaseStorageAvailableNames(arr)).toBe('4');
  });
});

错误日志 #

FAIL  src/helpers/tests/firestoreHelpers.test.ts
  ● Test suite failed to run

    ReferenceError: TextDecoder is not defined

      1 | // Firebase
      2 | import { initializeApp } from 'firebase/app';
    > 3 | import { browserSessionPersistence, getAuth, setPersistence } from 'firebase/auth';    
        | ^
      4 | import { getFirestore } from 'firebase/firestore';
      5 | import { getDatabase } from 'firebase/database';
      6 | import { getStorage } from 'firebase/storage';

      at Object.<anonymous> (node_modules/@fastify/busboy/lib/utils/decodeText.js:4:21)
      at Object.<anonymous> (node_modules/@fastify/busboy/lib/utils/parseParams.js:4:20)
      at Object.<anonymous> (node_modules/@fastify/busboy/lib/types/multipart.js:15:21)
      at Object.<anonymous> (node_modules/@fastify/busboy/lib/main.js:7:25)
      at Object.<anonymous> (node_modules/undici/lib/fetch/body.js:3:16)
      at Object.<anonymous> (node_modules/undici/lib/fetch/response.js:4:47)
      at Object.<anonymous> (node_modules/undici/index.js:119:29)
      at Object.<anonymous> (node_modules/@firebase/auth/dist/node/totp-e9be401a.js:7:14)        
      at Object.<anonymous> (node_modules/@firebase/auth/dist/node/index.js:5:12)
      at Object.<anonymous> (node_modules/firebase/auth/dist/index.cjs.js:5:12)
      at Object.<anonymous> (src/firebase/firebase.ts:3:1)
      at Object.<anonymous> (src/helpers/firesotreHelpers.ts:3:1)
      at Object.<anonymous> (src/helpers/tests/firestoreHelpers.test.ts:4:1)

Test Suites: 1 failed, 9 passed, 10 total
Tests: 150 passed, 150 total

项目依赖 #

"dependencies": {
    "@emotion/react": "^11.11.4",
    "@emotion/styled": "^11.11.0",
    "@fontsource/roboto": "^5.0.12",
    "@mui/icons-material": "^5.15.12",
    "@mui/material": "^5.15.12",
    "@reduxjs/toolkit": "^2.2.1",
    "@testing-library/jest-dom": "^5.17.0",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "@types/jest": "^27.5.2",
    "@types/node": "^17.0.45",
    "@types/react": "^18.2.65",
    "@types/react-dom": "^18.2.21"
}

解决方法 #

原因 #

这个错误源于测试环境中缺少TextDecoder全局API——它是浏览器环境和Node.js 18+的内置API，但你的Node.js版本（对应@types/node@17.x）可能在测试环境中没有正确暴露这个API，或者依赖链中的undici/@fastify/busboy组件在测试时无法访问到它。

方案1：升级Node.js版本 #

把Node.js升级到18.x及以上的LTS版本，新版本默认全局提供TextDecoder，无需额外配置即可解决问题。

方案2：手动在测试环境注入TextDecoder #

在测试文件的顶部添加以下代码，手动将Node.js内置的TextDecoder挂载到全局：

// 针对JavaScript项目
global.TextDecoder = require('util').TextDecoder;

// 针对TypeScript项目，还需添加类型声明
declare global {
  var TextDecoder: typeof import('util').TextDecoder;
}

方案3：调整Jest测试环境配置 #

如果你的测试不需要浏览器DOM环境，可以修改jest.config.js将测试环境设置为node：

module.exports = {
  testEnvironment: 'node',
  // 其他已有配置...
};

如果是React组件测试需要保留jsdom环境，优先选择方案1或2。

内容的提问来源于stack exchange，提问作者Richardson