基于CRA的ES6+TypeScript+MUI项目Jest测试配置问题

核心问题根源 #

手动修改Jest/Babel配置、替换CRA默认的react-scripts test命令，会破坏CRA内置的TS/JSX/ES模块集成逻辑，导致两个典型错误：

1. MUI包的ES模块代码未被转译，Jest无法识别import语法
2. TSX文件的JSX语法未被正确处理

标准配置步骤（无需eject） #

1. 锁定依赖版本 #

确保package.json中依赖版本匹配，避免版本冲突：

{
  "dependencies": {
    "@mui/material": "^5.14.0",
    "@emotion/react": "^11.11.0",
    "@emotion/styled": "^11.11.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "typescript": "^5.1.0"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^6.0.0",
    "@testing-library/react": "^14.0.0",
    "@testing-library/user-event": "^14.4.0",
    "@types/jest": "^29.5.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "react-scripts": "5.0.1"
  }
}

执行npm install安装依赖。

2. 保留CRA默认测试命令 #

不要替换react-scripts test，保持scripts配置：

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

3. 配置TSConfig支持JSX #

修改tsconfig.json，确保JSX语法被正确编译：

{
  "compilerOptions": {
    "target": "ES6",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx" // 关键配置，启用React 17+的JSX转换
  },
  "include": ["src"]
}

4. 让Jest转译MUI相关包 #

在package.json中添加Jest配置，排除MUI及依赖包的转译忽略规则：

"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!@mui/material|@mui/utils|@emotion/react|@emotion/styled)"
  ]
}

解释：CRA默认忽略node_modules的转译，但MUI部分包使用ES模块语法，需要让Babel转译这些包以适配Jest的CommonJS环境。

5. 标准测试文件示例 #

创建符合规范的App.test.tsx：

import { render, screen } from '@testing-library/react';
import App from './App';
import '@testing-library/jest-dom'; // 扩展Jest断言能力

test('渲染核心内容', () => {
  render(<App />);
  const titleElement = screen.getByText(/你的应用标题/i);
  expect(titleElement).toBeInTheDocument();
});

错误针对性解决 #

• MUI import语法错误：通过transformIgnorePatterns配置，让Jest转译MUI相关的ES模块包，解决"Cannot use import statement outside a module"问题。
• JSX语法未启用：确保tsconfig.json的jsx字段为react-jsx，测试文件后缀为.tsx，同时不要修改CRA默认的Babel配置。

现代测试工具替代建议 #

如果觉得CRA的配置限制过多，推荐使用Vite + Vitest组合：

• Vitest是Vite生态下的测试工具，原生支持ES模块、TS/JSX，速度远超Jest，配置更简洁。

基础配置步骤 #

1. 安装依赖：

npm install -D vitest @testing-library/react @testing-library/jest-jsdom jsdom @vitejs/plugin-react

2. 创建vite.config.ts：

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom', // 模拟浏览器环境
    globals: true, // 无需手动导入describe/test等全局函数
    setupFiles: './src/setupTests.ts' // 全局测试配置
  }
});

3. 创建src/setupTests.ts：

import '@testing-library/jest-dom/vitest'; // 扩展断言

4. 修改package.json的scripts：

"scripts": {
  "test": "vitest",
  "test:ui": "vitest --ui" // 可选：启用可视化测试界面
}

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