用 ts-jest 在 Jest 中测试 TypeScript 项目:带 Source Map 支持的类型检查型 Transformer 全解析

原创2026-10-06 18:16:471,869 阅读
文章标签:测试开发工具

用 ts-jest 在 Jest 中测试 TypeScript 项目:带 Source Map 支持的类型检查型 Transformer 全解析

ts-jest 是一个带 Source Map 支持的 Jest transformer)为核心骨架,结合仓库源码与配套文档,为你梳理 ts-jest 的能力边界、与 Babel 方案的取舍、快速上手步骤、核心配置以及底层处理流程,读完后你将能独立完成 TypeScript 项目的 Jest 测试环境搭建与调优。

ts-jest 是什么

根据项目官方定位(见 README.md 与 website/docs/introduction.md):

ts-jest 是一个带 Source Map 支持的 Jest transformer,它让你可以使用 Jest 测试用 TypeScript 编写的项目。

围绕这一定位,有三个关键能力值得展开:

  1. 它是一个 Jest transformer:在 Jest 的代码转换链路中,ts-jest 通过 Jest 的 transform 配置被挂载到 .ts/.tsx 等文件的处理流程上,负责把这些文件编译成 Jest 可以执行的 JavaScript。
  2. 带 Source Map 支持:编译产物会携带 Source Map,因此当测试失败或抛出异常时,Jest 能够把堆栈信息映射回原始的 .ts 源文件,错误定位准确、调试体验友好。
  3. 支持 TypeScript 的全部特性,包括类型检查:这是 ts-jest 区别于纯转译方案(如 Babel)的核心卖点——它不只是"去掉类型注解",而是真正以 TypeScript 编译器 API 驱动,在测试运行的同时进行类型检查(见 website/docs/babel7-or-ts.md)。

一个值得注意的细节是:ts-jest 项目自身也使用 ts-jest 来测试自己(README 的 "Built With" 一节明确写了 ts-jest uses itself for its tests)。这意味着该项目每天都要在"自己编译自己、自己测试自己"的场景下运行,其 transformer 的正确性与健壮性由项目自身的测试套件背书。

入口与实现:一个 "createTransformer" 的包

从源码结构看,ts-jest 的对外入口非常简洁。在 src/index.ts 中,包默认导出了一个包含 createTransformer(tsJestConfig?) 方法的对象,该方法返回 TsJestTransformer 实例:

export default {
  createTransformer(tsJestConfig?: TsJestTransformerOptions) {
    return new TsJestTransformer(tsJestConfig)
  },
}

TsJestTransformer 的核心实现位于 src/legacy/ts-jest-transformer.ts,它实现了 Jest 的 SyncTransformer 接口,提供了 process / processAsync / getCacheKey / getCacheKeyAsync 等方法,并在构造时缓存 ConfigSet、维护编译器实例与依赖图(depGraphs),从而保证同一测试进程中多次转换可以复用编译结果。

为什么需要 transformer:Jest 并不原生理解 TypeScript

Jest 本身只能直接执行 JavaScript。对于 .ts/.tsx 文件,Jest 需要借助 transformer 在 require() 之前将其转换为 JavaScript。ts-jest 正是承担这一职责的官方推荐的 TypeScript transformer。

安装并配置好 ts-jest 后,Jest 对每个文件的处理流程大致是:

  1. 判断该文件是否有对应的 transform 规则;
  2. 若 transformer 提供了 getCacheKey,则用它计算缓存键;
  3. 若命中缓存则直接使用缓存内容,否则调用 transformer.process(...) 编译文件并更新缓存;
  4. 最终 require() 编译后的产物。

这一流程的详细 PlantUML 描述见仓库内部文档 website/docs/processing.md。

ts-jest 与 Babel7 + @babel/preset-typescript 的对比

2018 年 9 月 Babel 7 发布,带来了 @babel/preset-typescript,目标是让 Babel 用户无需迁移即可通过添加一个 preset 来尝试 TypeScript。那么既然 Babel 也能处理 TypeScript 语法,为什么还需要 ts-jest?

官方文档 website/docs/babel7-or-ts.md 系统性地列出了 @babel/preset-typescript 的局限——以下这些 TypeScript(与 ts-jest)能做到、而 Babel 做不到的事情,正是选择 ts-jest 的关键理由。

没有类型检查

这是使用 TypeScript(而非 Babel)的最大优势:开箱即用的类型检查。

在使用 ts-jest 时,文件在编译的同时会被类型检查,从而获得更流畅的 TDD(测试驱动开发)体验。下面这段代码,TypeScript 会直接报错,而 Babel 则不会:

const str: string = 42

Babel 将文件当作相互孤立的模块逐一转译,不存在"项目"的概念;而 TypeScript 中文件属于一个项目(project),是在项目作用域内统一编译的。这意味着跨文件的类型关系、import 类型推断等都能被正确校验。

不支持 namespace

namespace app {
  export const VERSION = '1.0.0'
  export class App {
    /* ... */
  }
}

Babel 的 preset-typescript 无法处理这种命名空间语法。

不支持 const enum

const enum Directions {
  Up,
  Down,
  Left,
  Right,
}

const enum 会被 TypeScript 编译器内联展开,Babel 按文件独立转译时无法完成这种跨文件的内联。

不支持声明合并

Babel 无法处理 enum、namespace 等类型的声明合并(declaration merging)特性。

不支持 legacy import/export

import lib = require('lib')
// ...
export = myVar

这类历史遗留的导入导出语法同样超出 Babel preset 的能力范围。

开启 JSX 时不支持尖括号类型断言

const val = <string>input

当 TSX/JSX 开启时,尖括号会被解析为 JSX 语法,Babel 无法把它当作类型断言处理,而 ts-jest 基于 TypeScript 编译器则没有这个问题。

总结:如果你的项目用到了上述任一特性,或者希望在测试运行过程中同步获得类型检查保障,ts-jest 是比 Babel + preset-typescript 更完整的选择。

快速开始:安装、配置与运行

以本仓库官方文档 website/docs/getting-started/installation.md 为准,最快三步即可跑通。

1. 安装依赖

将 jest、typescript、ts-jest 与 @types/jest 一次性安装为开发依赖:

npm install --save-dev jest typescript ts-jest @types/jest

如果你的项目使用 TypeScript 7,不要直接安装 typescript,而应遵循官方推荐的并排(side-by-side)编译器方案,详见 website/docs/guides/typescript-7.md。

2. 创建 Jest 配置

默认情况下 Jest 无需任何配置文件即可运行,但它不会编译 .ts 文件。要让 Jest 使用 ts-jest 转译 TypeScript,需要创建一份告知 Jest 使用 ts-jest preset 的配置文件。

ts-jest 可以自动生成配置文件:

npx ts-jest config:init

使用 yarn 时对应:

yarn ts-jest config:init

该命令会创建一份基础的 Jest 配置文件,告知 Jest 如何正确处理 .ts 文件。如果你在安装时遇到 npx: command not found 之类的报错,可以把 npx XXX 替换为 node node_modules/.bin/XXX(在项目根目录下执行)。

此外,你也可以使用 create-jest 命令(同样以 npx 或 yarn 前缀)来获得更多 Jest 相关选项;但对其中的 TypeScript 询问要回答 no,然后在生成的 jest.config.js 中手动加入一行:preset: "ts-jest"。

官方给出的全流程速查表如下:

步骤 npm yarn
前置依赖(TypeScript 4.3–6) npm i -D jest typescript yarn add --dev jest typescript
安装 npm i -D ts-jest @types/jest yarn add --dev ts-jest @types/jest
创建配置 npx ts-jest config:init yarn ts-jest config:init
运行测试 npm test 或 npx jest yarn test 或 yarn jest

3. 运行测试

直接执行 npm test 或 npx jest 即可。此时 .ts/.tsx 文件会被 ts-jest 转译,且转换产物携带 Source Map,错误堆栈会指向原始 TypeScript 源码。

相关配置入口

如需进一步定制 Jest,请参考 Jest 官方配置指南;ts-jest 特有的配置项汇总在 website/docs/getting-started/options.md。若使用 ESM 项目,还需要阅读 website/docs/guides/esm-support.md。

核心配置选项一览

所有 ts-jest 专属选项都可以定义在 Jest 的 transform 配置对象中,既可以写在 package.json 里,也可以通过 jest.config.js 或 jest.config.ts 文件提供。

当使用 TypeScript 编写 Jest 配置文件时,Jest 会借助 ts-node 来编译该配置文件,ts-jest 不参与这一过程(见 website/docs/getting-started/options.md 的注意事项)。

官方列出的选项总表如下:

选项 说明 类型 默认值
compiler 用作编译器的 TypeScript 模块 string "typescript"
tsconfig TypeScript 编译相关配置 string|object|boolean auto
isolatedModules 关闭类型检查(按隔离模块编译) boolean disabled
astTransformers 自定义 TypeScript AST 转换器 object auto
diagnostics 诊断信息相关配置 boolean|object enabled
babelConfig Babel(Jest) 相关配置 boolean|string|object disabled
stringifyContentPathRegex 匹配的文件将变成返回自身内容的模块 string|RegExp disabled
useESM 启用 ESM 支持 boolean auto

注意:如果你使用自定义的 transform 配置,请从 Jest 配置中移除 preset,避免 Jest 不能正确转换文件(官方文档明确警告过这一点)。

tsconfig 选项的三种用法

tsconfig 选项允许你指定要使用的 tsconfig JSON 文件,也可以直接内联一份 compilerOptions 对象(详见 website/docs/getting-started/options/tsconfig.md)。

默认情况下,ts-jest 会在你的项目中查找 tsconfig.json;若找不到,则使用 TypeScript 默认的 compilerOptions,唯一例外是 target 使用 ES2015 而不是默认的 ES5。如果你希望即使项目里存在 tsconfig.json 也强制使用默认值,可以将该选项设为 false。

指定配置文件路径(路径相对于启动 Jest 的目录,也支持 <rootDir> 前缀):

import type { Config } from 'jest'

const jestConfig: JestConfigWithTsJest = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' 处理 ts,js,tsx,jsx
    // '^.+\\.m?[tj]sx?$' 处理 ts,js,tsx,jsx,mts,mjs,mtsx,mjsx
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: 'tsconfig.test.json',
      },
    ],
  },
}

export default jestConfig

内联 compilerOptions(等同于写在 tsconfig.json 的 compilerOptions 里的对象):

const jestConfig: Config = {
  // [...]
  transform: {
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: {
          importHelpers: true,
        },
      },
    ],
  },
}

禁用自动查找:

const jestConfig: Config = {
  // [...]
  transform: {
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        tsconfig: false,
      },
    ],
  },
}

isolatedModules:以性能换取类型检查

默认情况下 ts-jest 在"项目"上下文中使用 TypeScript 编译器,具备完整的类型检查与全部特性。但它也可以把每个文件当作独立的"隔离模块"分别编译,这就是 isolatedModules 选项(默认 false)的作用(详见 website/docs/getting-started/options/isolatedModules.md)。

开启后会失去类型检查能力,以及 const enum 等特性;但在配合 jest --no-cache 运行时,测试会明显更快:

const jestConfig: Config = {
  // [...]
  transform: {
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        isolatedModules: true,
      },
    ],
  },
}

注意:该配置页已被标记为 DEPRECATED,官方建议改用 tsconfig.json 中的 isolatedModules 选项,未来大版本中会移除 ts-jest 侧的 isolatedModules 配置。

性能提示与注意事项

使用 isolatedModules: false(即开启类型检查)时性能相对更慢,可以通过收窄 tsconfig.json 中 include 的文件范围来提升性能——include 提供的文件越少,测试运行能获得的性能提升越大:

{
  // ...其他配置
  "include": ["my-typings/*", "my-global-modules/*"]
}

但代价是 ts-jest 可能无法识别所有打算配合 Jest 使用的文件,自定义类型、全局模块等可能出问题。官方给出的建议是:让测试环境真正需要的文件被 include 的 glob 模式覆盖到,从而兼顾性能提升与不破坏现有行为。

预设(Presets)与编程式配置

Jest 中的 preset 是预定义的配置,用来标准化测试环境的搭建。ts-jest 提供了多组高度定制化的 preset,官方推荐的最佳实践是调用 preset 创建函数来生成(并可扩展)配置,而将旧的字符串形式 preset 视为 legacy 方案(详见 website/docs/getting-started/presets.md)。

以最常用的 createDefaultPreset 为例(其实现见 src/presets/create-jest-preset.ts):

import { createDefaultPreset, type JestConfigWithTsJest } from 'ts-jest'

const presetConfig = createDefaultPreset({
  //...options
})

const jestConfig: JestConfigWithTsJest = {
  ...presetConfig,
}

export default jestConfig

createDefaultPreset(options) 返回一个包含 transform 属性的对象,将 '^.+.tsx?$' 映射到 <a href="https://link.gitcode.com/i/7f65063c3b0452bb554804485d338fd7" target="_blank">'ts-jest', TsJestTransformerOptions]。可选参数包括 tsconfig、isolatedModules、compiler、astTransformers、diagnostics、stringifyContentPathRegex,每个参数都有独立的官方说明页(见 [website/docs/getting-started/options 下的子页面)。

除默认 preset 外,ts-jest 还提供:

  • createDefaultLegacyPreset:legacy 版默认配置,transform 指向 ts-jest/legacy;
  • createDefaultEsmPreset:ESM 配置,处理 .ts/.mts/.tsx/.mtsx,并额外设置 extensionsToTreatAsEsm 与 useESM: true;
  • createJsWithTsPreset:同时处理 JS 与 TS 文件(.js/.jsx/.ts/.tsx);
  • createJsWithTsEsmPreset:ESM 版 JS+TS 配置;
  • createJsWithBabelPreset 及 ESM/legacy 变体:TS 文件交给 ts-jest,JS 文件交给 babel-jest。

从源码可以看到这些函数的真实返回结构,例如 createJsWithBabelPreset 在 src/presets/create-jest-preset.ts 中同时设置了 [JS_TRANSFORM_PATTERN]: 'babel-jest' 与 [TS_TRANSFORM_PATTERN]: ['ts-jest', ...] 两条规则。

旧式字符串 preset(如 ts-jest/presets/default、ts-jest/presets/js-with-ts 等)仍可使用,但官方明确警告:ts-jest 不推荐使用 legacy preset,因为这种方式不利于灵活配置 Jest,且会在下个大版本中移除,用户被强烈建议迁移到上述函数式写法。

底层处理流程:从源文件到可执行代码

如果你关心 ts-jest 内部到底做了什么,仓库内部文档 website/docs/processing.md 给出了完整的处理流程(该文档定位为贡献者内部文档)。结合 src/legacy/ts-jest-transformer.ts 的实现,整个转换链路可以概括为:

  1. 入口 tsJest.process(source):Jest 调用 transformer 的 process 方法,传入源文件内容与转换配置。
  2. 可选的字符串化:若命中 stringifyContentPathRegex,文件内容会被 JSON 序列化为模块(常用于把 .json、模板等文件直接变成返回自身内容的模块)。
  3. .d.ts 声明文件直接清空内容:定义文件无需编译,直接产出空内容。
  4. 编译器选择:若未开启隔离模块,则创建并缓存 TypeScript Language Service,以"项目"上下文编译;若开启,则逐文件用 transpileModule 独立编译。
  5. 持久缓存检查:命中持久缓存则直接恢复内存缓存,否则执行编译。
  6. 自定义 AST transformers:在这里执行 jest.mock 的提升(hoisting)以及用户基于配置定义的 AST 转换(对应 astTransformers 选项)。
  7. 修复 Source Map:对编译产物修正 Source Map,更新内存缓存与持久缓存。
  8. 可选 Babel 二次处理:若配置了 babelConfig,调用 babel-jest 的 process 再次转换。
  9. afterProcess 钩子:若存在该钩子且返回了内容,则以其返回值作为新源码。

从 src/legacy/ts-jest-transformer.ts 可以看到,TsJestTransformer 实现了 Jest 的 SyncTransformer,并通过静态缓存 _cachedConfigSets 在不同测试运行之间复用 ConfigSet 与编译器实例,这正是 ts-jest 在 watch 模式下依然能保持较快编译速度的实现基础。

版本策略与注意事项

ts-jest 不采用语义化版本(SemVer)。官方在 website/docs/introduction.md 中特别强调:

我们不进行语义化版本管理,23.10 是一次重写。运行 npm i -D ts-jest@"<23.10.0" 可以回退到之前的版本。

这意味着从旧版本升级到 23.10 及以上时,需要留意可能的行为变化;如果需要兼容旧行为,可以用上面的命令锁定 <23.10.0 版本。项目主版本号跟随 Jest 的主版本,但整体版本策略并非严格 SemVer(详见 README.md 的 Versioning 一节)。

另外,website/docs/getting-started/version-checking.md 记载了一个已被标记 DEPRECATED 的版本检查机制:ts-jest 默认支持一个范围的 jest/typescript 版本,使用不兼容版本时会收到警告,可通过设置环境变量 TS_JEST_DISABLE_VER_CHECKER=true 关闭(Linux/macOS 用 export,Windows 用 set)。该机制已废弃,未来将由 package.json 中原生的 peerDependencies 检查取代。

TypeScript 7 用户的特别说明

如果你的项目使用 TypeScript 7,官方建议采用并排编译器方案(详见 website/docs/guides/typescript-7.md):TypeScript 7.0 自带原生 tsc,但不提供 ts-jest 转换所需的 JavaScript 编译器 API。应通过 npm 别名同时安装两个编译器:

npm install --save-dev '@typescript/native@npm:typescript@^7.0.2' 'typescript@npm:@typescript/typescript6@^6.0.2'

这样 npx tsc 运行原生 TypeScript 7 编译器,而 ts-jest 通过 typescript 别名获得其需要的 TypeScript 6 JavaScript API。不要将 ts-jest 的 compiler 选项指向 @typescript/native,因为 TypeScript 7.0 没有兼容的 JavaScript API,ts-jest 会在加载该包时提前停止并给出可操作的配置错误。

小结

ts-jest 以"带 Source Map 支持的 Jest transformer"为定位,提供了 Babel 方案所不具备的完整类型检查与全部 TypeScript 特性支持。通过本文你可以:

  • 理解 ts-jest 与 Babel7 + @babel/preset-typescript 的取舍(类型检查、namespace、const enum、声明合并、legacy 导入导出、JSX 下尖括号断言等);
  • 按速查表完成安装、config:init 配置与测试运行;
  • 掌握 tsconfig、isolatedModules、diagnostics、astTransformers 等核心选项及其默认行为;
  • 了解底层编译流程与缓存机制,为性能调优和问题排查打基础;
  • 明确非 SemVer 版本策略与 TypeScript 7 的并排安装方案。

需要继续深入时,可依次阅读仓库中的 website/docs/getting-started/installation.md、website/docs/getting-started/options.md、website/docs/getting-started/presets.md 以及 website/docs/processing.md,并结合 src/legacy/ts-jest-transformer.ts 与 src/presets/create-jest-preset.ts 阅读源码实现。

登录后查看全文
ts-jest