Jest-extended 测试库配置指南：从基础到高级

Jest-extended 测试库配置指南：从基础到高级

前言

Jest-extended 是一个强大的 Jest 测试框架扩展库，它为开发者提供了更多实用的断言匹配器(matchers)，能够显著提升测试代码的可读性和表达能力。本文将详细介绍如何正确配置和使用这个库。

环境要求

在使用 jest-extended 之前，必须确保满足以下环境要求：

• Jest 版本必须 ≥ 27.2.5
• 如果使用较旧版本的 Jest，只能使用 jest-extended 1.2.1 版本

基础配置

1. 创建初始化脚本

首先需要创建一个测试初始化脚本，通常命名为 testSetup.js，内容如下：

// 方式一：导入所有匹配器
import * as matchers from 'jest-extended';
expect.extend(matchers);

// 方式二：选择性导入特定匹配器
import { toBeArray, toBeSealed } from 'jest-extended';
expect.extend({ toBeArray, toBeSealed });

2. 修改 Jest 配置

在项目的 package.json 文件中，添加或修改 Jest 配置：

"jest": {
  "setupFilesAfterEnv": ["./testSetup.js"]
}

或者使用更简洁的方式直接引入所有匹配器：

"jest": {
  "setupFilesAfterEnv": ["jest-extended/all"]
}

高级配置

与 Vitest 集成

由于 Vitest 的 API 与 Jest 兼容，jest-extended 也可以与 Vitest 配合使用。

1. 创建 Vitest 初始化脚本

import { expect } from 'vitest';
import * as matchers from 'jest-extended';
expect.extend(matchers);

2. 配置 Vitest

在 vitest.config.js 中添加配置：

export default defineConfig({
  test: {
    setupFiles: ['./testSetup.js'],
  },
});

TypeScript 类型支持

对于使用 TypeScript 的项目，需要额外配置类型声明。

Vitest ≥ 0.31.0 的配置

创建 jest-extended.d.ts 文件：

import type CustomMatchers from 'jest-extended';
import 'vitest';

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining<T = any> extends CustomMatchers<T> {}
  interface ExpectStatic<T = any> extends CustomMatchers<T> {}
}

自定义匹配器扩展示例

import type CustomMatchers from 'jest-extended';
import 'vitest';

interface MyCustomMatchers {
  toBeFoo(): any;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T>, MyCustomMatchers {}
  interface AsymmetricMatchersContaining<T = any> extends CustomMatchers<T>, MyCustomMatchers {}
  interface ExpectStatic extends CustomMatchers, MyCustomMatchers {}
}

Vitest < 0.31.0 的配置

import type CustomMatchers from 'jest-extended';
import 'vi';

declare module 'vi' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining<T = any> extends CustomMatchers<T> {}
  interface ExpectStatic<T = any> extends CustomMatchers<T> {}
}

最佳实践建议

1. 按需导入：虽然可以一次性导入所有匹配器，但建议只导入实际需要的匹配器，这样可以保持测试环境的精简。

2. 版本管理：定期检查 jest-extended 和测试框架的版本兼容性，避免因版本问题导致的测试失败。

3. 类型安全：对于 TypeScript 项目，确保类型声明文件正确配置，以获得完整的类型提示和检查。

4. 团队统一：在团队项目中，建议统一配置方式，避免因个人配置差异导致的问题。

通过以上配置，你就可以在项目中充分利用 jest-extended 提供的强大断言功能，编写更加清晰、表达力更强的测试代码了。