跨平台Jest代码覆盖率异常：Windows正常，Mac/Ubuntu CI不符预期

1. 修正路径匹配与大小写问题 #

Unix系系统（Mac/Ubuntu）的路径分隔符为/，且区分文件名大小写，Windows则相反，这是最常见的跨平台覆盖率偏差原因：

• 调整collectCoverageFrom为相对路径+通配符，避免绝对路径匹配失败：

  // jest.config.js
  module.exports = {
    collectCoverageFrom: [
      'src/**/*.{ts,tsx}',
      '!src/**/*.d.ts',
      '!src/**/*.spec.{ts,tsx}'
    ]
  }
  

• 检查所有组件导入的文件名大小写是否与实际文件一致（比如import Loader from './loader.tsx'和实际Loader.tsx在Ubuntu下会被视为不同文件，导致覆盖率无法收集）。

2. 禁用Jest缓存并清理CI环境缓存 #

并行执行或缓存污染可能导致覆盖率统计异常：

• 测试时强制禁用缓存：

  npm test -- --no-cache --coverage
  

• 在GitHub Actions配置中添加缓存清理步骤：

  - name: Clean Jest cache
    run: npx jest --clearCache
  

3. 统一TypeScript编译与Jest配置 #

确保Jest正确处理TSX文件，且编译配置在跨平台下一致：

• 使用单独的Jest专属TS配置（tsconfig.jest.json），避免与Next.js编译冲突：

  {
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "jsx": "react-jsdom",
      "module": "CommonJS"
    },
    "include": ["src/**/*.{ts,tsx}", "src/**/*.spec.{ts,tsx}"]
  }
  

• 在Jest配置中指定该TS配置：

  transform: {
    '^.+\\.(ts|tsx)$': ['ts-jest', { tsconfig: 'tsconfig.jest.json' }],
  }
  

4. 对齐测试环境依赖与版本 #

CI环境的Node版本、依赖安装方式可能与本地不同：

• 在GitHub Actions中固定Node版本，与本地保持一致：

  - name: Setup Node.js
    uses: actions/setup-node@v4
    with:
      node-version: '18.x' # 替换为你本地使用的Node版本
      cache: 'npm'
  

• 确保CI使用npm ci而非npm install，保证依赖版本与package-lock.json完全一致。

5. 调试覆盖率差异细节 #

通过生成覆盖率JSON文件，对比跨平台的统计差异：

• 在CI中运行测试时生成JSON格式的覆盖率报告：

  npm test -- --coverage --coverageReporters=json
  

• 将CI生成的coverage/coverage.json下载到本地，与Windows下的同文件对比，定位具体哪些代码分支、文件的覆盖率统计不一致。
• 针对Loader组件的--runInBand异常，单独执行测试并添加--verbose参数，查看测试执行的详细日志，确认是否存在异步代码未等待完成（比如未正确使用RTL的waitFor）导致代码未被覆盖。

6. 检查Jest覆盖率规则配置 #

确保CI环境的覆盖率收集规则与本地一致：

• 确认jest.config.js中collectCoverage、coverageThreshold等配置没有被CI环境的变量或条件逻辑覆盖；
• 避免在CI中使用不同的Jest配置文件（比如jest.config.ci.js），除非明确需要且经过验证。

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