当使用 vitest 进行单元测试时，如果项目中混用了 commonjs 的 `require` 语法而非 es modules 的 `import` 语法，可能会遇到 `vi.mock` 无法正确模拟依赖的问题。本文将深入探讨这一常见陷阱的根本原因，并提供将测试代码及其依赖迁移至 es modules 的解决方案，确保 vitest 的模块模拟机制能够有效工作，从而构建稳定可靠的测试环境。
Vitest Mock 的意外失效
在使用 Vitest 进行单元测试时，我们经常需要模拟（mock）外部依赖，以隔离被测试模块并控制其行为。Vitest 提供了强大的 vi.mock API 来实现这一目标。然而，有时开发者会发现即使正确配置了 vi.mock，被模拟的模块在测试运行时仍然是其真实实现，而非模拟版本。
考虑以下测试代码片段：
import { it, describe, expect, vi, beforeEach } from 'vitest';
const ClientAuthenticator = require('../src/client-authenticator'); // 使用 require
const { ssmClient, getParameterCommand } = require('../src/helpers/aws'); // 使用 require
const ssmClientMock = vi.fn();
const getParameterCommandMock = vi.fn();
vi.mock('../src/helpers/aws', () => {
return {
ssmClient: ssmClientMock,
getParameterCommand: getParameterCommandMock,
};
});
describe('ClientAuthenticator.authenticator Tests', () => {
it('Should set correct client name', async () => {
// Arrange
console.log(ssmClient); // 预期输出 mock，实际输出真实实现
const clientId = 'clientId';
const clientSecret = 'clientSecret';
// ... rest of the test ...
});
});在这个例子中，我们尝试使用 vi.mock 来模拟 ../src/helpers/aws 模块中的 ssmClient 和 getParameterCommand。然而，在测试执行时，console.log(ssmClient) 却打印出了 ssmClient 的真实实现，而不是我们期望的 ssmClientMock。这表明 vi.mock 并未成功拦截并替换该模块。
根本原因：Vitest 与模块系统的兼容性
造成 vi.mock 失效的根本原因在于 JavaScript 的模块系统。Vitest 的模块模拟机制，特别是 vi.mock，是围绕 ES Modules (ESM) 标准设计的。当 Vitest 运行时，它会拦截 ES Modules 的加载过程，并在模块导入（import）时注入模拟版本。
然而，当代码中使用 CommonJS (CJS) 的 require 语法来导入模块时，Vitest 的 ESM 拦截机制就无法生效。require 函数有其自己的模块解析和加载逻辑，它会直接加载模块的真实实现，绕过了 Vitest 为 ESM 准备的模拟钩子。因此，即使你使用了 vi.mock，如果你的测试文件或被测试/模拟的模块仍然使用 require，Vitest 也无法将其替换为模拟版本。
简而言之，Vitest 的 vi.mock 期望你的代码和测试都采用 ES Modules 规范。
解决方案：拥抱 ES Modules
解决这个问题的最直接和推荐的方法是统一使用 ES Modules。这意味着你需要将你的测试文件以及任何被测试或被模拟的模块从 CommonJS 转换为 ES Modules。
1. 将测试文件转换为 ES Modules
首先，将你的测试文件中的 require 语句替换为 import 语句。
修改前：
const ClientAuthenticator = require('../src/client-authenticator');
const { ssmClient, getParameterCommand } = require('../src/helpers/aws');修改后：
import ClientAuthenticator from '../src/client-authenticator';
import { ssmClient, getParameterCommand } from '../src/helpers/aws';完整的测试文件示例如下：
import { it, describe, expect, vi, beforeEach } from 'vitest';
import ClientAuthenticator from '../src/client-authenticator'; // 使用 import
import { ssmClient, getParameterCommand } from '../src/helpers/aws'; // 使用 import
const ssmClientMock = vi.fn();
const getParameterCommandMock = vi.fn();
vi.mock('../src/helpers/aws', () => {
return {
ssmClient: ssmClientMock,
getParameterCommand: getParameterCommandMock,
};
});
describe('ClientAuthenticator.authenticator Tests', () => {
it('Should set correct client name', async () => {
// Arrange
console.log(ssmClient); // 现在应该输出 mock 了
const clientId = 'clientId';
const clientSecret = 'clientSecret';
// ... rest of the test ...
});
});2. 确保被测试和被模拟的模块也使用 ES Modules
为了让 import 语句正常工作，并确保 Vitest 的模拟机制能够全面生效，你的被测试模块 (client-authenticator.js) 和被模拟模块 (helpers/aws.js) 也应该导出为 ES Modules 格式。
CommonJS 模块示例 (helpers/aws.js - 修改前):
// helpers/aws.js (CommonJS)
const AWS = require('aws-sdk'); // 假设这里使用了 AWS SDK
const ssmClient = new AWS.SSM();
function getParameterCommand(name) {
return ssmClient.getParameter({ Name: name }).promise();
}
module.exports = {
ssmClient,
getParameterCommand,
};ES Modules 模块示例 (helpers/aws.js - 修改后):
// helpers/aws.js (ES Modules)
import AWS from 'aws-sdk'; // 假设这里使用了 AWS SDK
const ssmClient = new AWS.SSM();
export function getParameterCommand(name) {
return ssmClient.getParameter({ Name: name }).promise();
}
export { ssmClient }; // 导出 ssmClient3. 配置 package.json
为了让 Node.js 和 Vitest 正确地将 .js 文件解释为 ES Modules，你需要在项目的 package.json 文件中添加 "type": "module"：
{
"name": "my-project",
"version": "1.0.0",
"type": "module", // 添加这一行
"main": "index.js",
"scripts": {
"test": "vitest"
},
"devDependencies": {
"vitest": "^1.0.0"
}
}如果你的项目同时包含 CommonJS 和 ES Modules 文件，并且你无法全局设置 "type": "module"，你可以使用 .mjs 扩展名来明确指定 ES Modules 文件，或 .cjs 来指定 CommonJS 文件。例如，你的测试文件可以命名为 my-test.test.mjs。
注意事项与最佳实践
- 统一模块系统： 在使用 Vitest 时，强烈建议整个项目（包括源文件和测试文件）都统一采用 ES Modules。这不仅能解决模拟问题，还能带来更好的代码组织和 Tree Shaking 优化。
- 理解 vi.mock 的工作原理： vi.mock 是一种“提升（hoisting）”机制，它会在模块加载之前就对其进行替换。这意味着 vi.mock 调用必须在模块的顶层作用域，并且通常在任何 import 语句之前（尽管在 ES Modules 中，import 语句本身也会被提升）。
- 动态导入与模拟： 对于需要在运行时动态导入的模块（例如使用 import() 表达式），Vitest 同样能够对其进行模拟，但其行为可能与静态 import 略有不同。
- 官方文档： 遇到 Vitest 模拟问题时，查阅其官方文档是最佳实践。vi.mock 的详细行为和限制在 Vitest 官方 API 文档中有详细说明，例如 Vitest vi.mock 文档。
通过将你的代码和测试迁移到 ES Modules，并确保 package.json 配置正确，你将能够充分利用 Vitest 强大的模块模拟功能，构建出更健壮、更可靠的单元测试。
