Web Lion

Appearance

Jest 配置文件（jest.config.js） ​

配置项 ​

jest.config.js 详细介绍 ​

jest.config.js 是 Jest 测试框架的核心配置文件，用于定制测试执行规则、环境、模块处理、覆盖率统计等所有核心行为。它支持 CommonJS 模块化（.js）或 ESM 模块化（.mjs/package.json 中指定 type: module），默认位于项目根目录，也可通过 jest --config <路径> 指定自定义路径。

核心配置分类与详解 ​

一、基础配置（测试执行核心） ​

配置项类型默认值核心作用
testRegexstring[][]用正则表达式匹配测试文件（优先级低于 testMatch，两者二选一即可）。
testTimeoutnumber5000单个测试用例超时时间（毫秒），异步测试或真实接口测试需适当增大（如 10000）。
rootDirstring项目根目录测试文件的根目录，testMatch 等路径基于此目录解析。
rootsstring[]["<rootDir>"]用于查找测试文件和模块的根目录数组，限制 Jest 搜索范围以提升效率。
testEnvironmentstring"jsdom"测试运行环境：- "jsdom"：模拟浏览器环境（Vue/React 前端测试常用）- "node"：Node.js 环境（后端/工具库测试）- 自定义环境路径
testMatchstring[]匹配测试文件的路径规则（支持 glob 模式），指定哪些文件被视为测试文件。

二、模块解析与处理（适配项目目录结构） ​

配置项类型默认值核心作用
moduleFileExtensionsstring[]["js", "json", "jsx", "ts", "tsx", "node"]Jest 识别的文件扩展名，按顺序尝试解析（如导入 .vue 需添加 "vue"）。
moduleNameMapperobject{}模块路径映射（类似 Webpack 的 resolve.alias），用于简化导入和处理非 JS 模块
moduleDirectoriesstring[]["node_modules"]查找模块时的目录优先级，可添加自定义目录（如 ["src", "node_modules"]）。
transformobject{"^.+\\.[jt]s?$": "babel-jest"}转换器配置：指定文件如何被编译，适配 ES6+/TS/Vue 等
transformIgnorePatternsstring[]["/node_modules/"]忽略转换的文件路径（正则），如第三方模块无需编译（需转换的模块可排除，如 "/node_modules/(?!@my-org)/"）。
setupFilesstring[][]测试执行前运行的脚本（同步），用于初始化全局变量、环境配置（如 import "@/utils/global"）。
setupFilesAfterEnvstring[][]测试环境初始化后运行的脚本（异步），用于配置 Jest 断言、Vue Test Utils 全局配置（如 import "@vue/test-utils"）。

三、测试过滤与执行策略 ​

配置项类型默认值核心作用
testPathIgnorePatternsstring[]["/node_modules/"]忽略的测试文件路径（正则），如 ["/node_modules/", "/dist/"]。
collectCoverageFromstring[]["**/*.{js,jsx,ts,tsx}", "!**/node_modules/**", "!**/vendor/**"]统计代码覆盖率的文件范围（glob 模式），排除无需统计的文件。
coverageReportersstring[]["json", "lcov", "text", "clover"]覆盖率报告格式：
- "text"：终端输出
- "lcov"：生成 LCOV 文件（适配 Codecov 等工具）
- "html"：生成 HTML 报告（可本地打开查看）
coverageDirectorystring"<rootDir>/coverage"覆盖率报告输出目录。
coverageThresholdobject{}覆盖率阈值要求（未达标则测试失败），强制保证代码质量：
javascript<br>{ global: { branches: 80, functions: 80, lines: 80, statements: 80 }, "./src/utils/": { lines: 90 } }<br>
onlyChangedbooleanfalse仅运行修改过的文件对应的测试用例（开发时提升效率），需配合版本控制（Git）。

四、Mock 与全局配置 ​

配置项类型默认值核心作用
automockbooleanfalse自动模拟所有导入的模块（默认关闭，建议手动通过 jest.mock 控制）。
clearMocksbooleanfalse每个测试用例执行后清除所有 mock 函数的调用记录（避免用例间污染）。
resetMocksbooleanfalse每个测试用例执行后重置所有 mock 函数（保留实现，清除调用记录和实例）。
restoreMocksbooleanfalse每个测试用例执行后恢复被 jest.spyOn 监视的方法（避免全局污染）。
globalsobject{}定义测试环境中的全局变量，如 { "Vue": Vue, "__DEV__": true }。
unmockedModulePathPatternsstring[][]不被自动 mock 的模块路径（正则），如真实接口测试时排除 axios。

五、Vue 项目专属配置（适配 Vue 2/3） ​

Vue 项目需结合 vue-jest 和 Vue Test Utils，补充以下配置：

javascript
module.exports = {
  // 1. 识别 .vue 文件
  moduleFileExtensions: ["js", "vue", "json"],
  // 2. 映射 @ 到 src 目录（与 Vue CLI 一致）
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
    // 3. 忽略样式文件（用 stub 替代）
    "^.+\\.(css|scss|less)$": "jest-transform-stub",
  },
  // 4. 转换 .vue 和 JS 文件
  transform: {
    "^.+\\.js$": "babel-jest", // 编译 ES6+
    "^.+\\.vue$": "vue-jest", // 编译 .vue 文件（Vue 2 用 vue-jest@3，Vue 3 用 vue-jest@5）
  },
  // 5. 测试环境（Vue 前端测试用 jsdom）
  testEnvironment: "jsdom",
  // 6. 忽略 node_modules 中的 Vue 相关模块转换
  transformIgnorePatterns: ["/node_modules/(?!vue|@vue/shared)/"],
  // 7. 测试前初始化 Vue Test Utils
  setupFilesAfterEnv: ["<rootDir>/tests/setup.js"],
};

六、TypeScript 项目专属配置 ​

需配合 ts-jest 处理 TypeScript 文件：

javascript
module.exports = {
  preset: "ts-jest", // 预设 ts-jest 配置（简化配置）
  testEnvironment: "jsdom",
  moduleFileExtensions: ["ts", "tsx", "js", "vue", "json"],
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
  transform: {
    "^.+\\.vue$": "vue-jest",
    "^.+\\.tsx?$": ["ts-jest", { tsconfig: "<rootDir>/tsconfig.test.json" }], // 指定测试用 tsconfig
  },
};

完整配置示例（Vue 2 + Jest + Vue Test Utils） ​

javascript
// jest.config.js
module.exports = {
  // 基础配置
  testMatch: ["**/__tests__/**/*.spec.js", "**/?(*.)+(spec|test).js"],
  testEnvironment: "jsdom",
  testTimeout: 10000,
  rootDir: process.cwd(),
  roots: ["<rootDir>/src", "<rootDir>/tests"],

  // 模块解析
  moduleFileExtensions: ["js", "vue", "json"],
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
    "^.+\\.(css|scss|png|jpg|jpeg|gif|svg)$": "jest-transform-stub",
  },
  transform: {
    "^.+\\.js$": "babel-jest",
    "^.+\\.vue$": "vue-jest@3", // Vue 2 适配 vue-jest@3
  },
  transformIgnorePatterns: ["/node_modules/(?!vue|element-ui)/"],

  // 测试初始化
  setupFiles: ["<rootDir>/tests/setup.global.js"], // 同步初始化全局变量
  setupFilesAfterEnv: ["<rootDir>/tests/setup.jest.js"], // 配置断言/测试工具

  // 覆盖率配置
  collectCoverageFrom: [
    "src/**/*.{js,vue}",
    "!src/main.js", // 排除入口文件
    "!src/router/index.js", // 排除路由配置
    "!**/node_modules/**",
  ],
  coverageReporters: ["text", "html", "lcov"],
  coverageDirectory: "<rootDir>/tests/coverage",
  coverageThreshold: {
    global: {
      branches: 60,
      functions: 70,
      lines: 80,
      statements: 80,
    },
  },

  // Mock 配置
  clearMocks: true, // 每个用例后清除 mock 记录
  restoreMocks: true, // 恢复 spyOn 监视的方法
  globals: {
    "vue-jest": {
      compilerOptions: {
        preserveWhitespace: false, // 移除 Vue 模板中的空白字符（与项目配置一致）
      },
    },
  },
};

配置加载优先级 ​

Jest 会按以下顺序查找配置文件，找到后停止：

  1. 命令行参数（如 jest --testTimeout 10000）
  2. package.json 中的 jest 字段
  3. jest.config.js / jest.config.mjs / jest.config.cjs
  4. jest.json / jest.yml / jest.yaml

常用命令（配合配置使用） ​

命令作用
jest按配置执行所有测试用例
jest --coverage执行测试并生成覆盖率报告
jest --watch监听文件变化，自动重新运行相关测试（开发时高效）
jest --onlyChanged仅运行修改过的文件的测试用例
jest --config ./jest.config.custom.js使用自定义路径的配置文件

关键注意事项 ​

  1. 版本兼容性：vue-jest、ts-jest 等插件版本需与 Jest、Vue/TypeScript 版本匹配（如 Vue 2 不支持 vue-jest@5+）。
  2. 异步测试：测试异步逻辑（如接口请求）时，需确保 testTimeout 足够长，且用 async/await 处理异步操作。
  3. Mock 与真实接口：如需调用真实接口，避免 automock: true，手动控制 jest.mock 仅模拟非核心依赖。
  4. 覆盖率优化：collectCoverageFrom 需精准配置，避免统计第三方代码、入口文件等无需覆盖的内容。

要不要我帮你生成一份 项目专属配置模板，根据你的技术栈（Vue 2/3、TS/JS、是否使用 Element UI 等）定制化配置？

项目专属配置（Vue 2 + Jest + Vue Test Utils） ​

js
// jest.config.js
module.exports = {
  testEnvironment: "jsdom",
  preset: "@vue/cli-plugin-unit-jest",
  transform: {
    "^.+\\.vue$": "vue-jest",
    "^.+\\.js$": "babel-jest",
    // 处理SCSS等样式文件
    // 使用自定义转换器处理 SCSS
    "^.+\\.scss$":
      "<rootDir>/src/components/JestTest/public/jest-transform-scss.js",
  },
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
    // 关键：将原 auth.js 映射到测试用的 mock 文件
    "^@/utils/auth.js$": "<rootDir>/tests/mocks/auth.js",
    "^@/utils/auth$": "<rootDir>/tests/mocks/auth.js",
  },
  moduleFileExtensions: ["vue", "js", "json", "node", "scss"],
  testMatch: ["**/__tests__/**/*.spec.js", "**/__tests__/**/*.test.js"],
  transformIgnorePatterns: ["/node_modules/"],
  setupFiles: [
    // "./tests/setup/axiosTokenInterceptor.js", // 第一步：注入拦截器
    // "./tests/setup/axiosBaseUrlPatch.js", // 最优先加载，覆盖 Axios 行为
    //
    "./tests/setup/env.js",
    // "./tests/utils/setupFiles.js",
    // "./tests/setup/mockWindow.js",
    // "./tests/setup/axiosPatch.js", // 第一步：补丁 Axios 函数
    // "./tests/setup/axiosFix.js", // 第二步：模拟基础对象（可选）
    // /*"./test/setup/env.js", */ "./tests/setup/browserMocks.js",
  ], // 配置环境变量
  // verbose: true, // 显示详细日志
  // globals: {
  //   "process.env": {
  //     VUE_APP_BASE_API:
  //       "https://yingliancirclechain.com/financial-service-platform", // 直接指定测试环境的 baseURL
  //   },
  // },
};

Released under the MIT License.

Copyright © 2025-present Void Wind