Vitest Mock 在 CommonJS 环境中不生效的解决方案-js教程-PHP中文网

Vitest Mock 在 CommonJS 环境中不生效的解决方案

DDD

发布： 2025-11-05 16:21:25

原创

918人浏览过

Vitest Mock 在 CommonJS 环境中不生效的解决方案

当使用 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 语句。

修改前：

Sveil开源商城

Sveil开源商城是专业和创新的开源在线购物车的解决方案，是基于osCommerce 3 alpha 5 独立开发的项目。环境为PHP+MYSQL，使用了先进的AJAX技术和富互联网应用（RIA）的框架ExtJS，由Sveil.com提供重要的可用性改善及与网站交互界面速度更快，更高效。VERSION 1.0--修复bug1、网站在维护2、当搜索引擎被激活，与我们联系功能不起作用。3、当SEO被激

查看详情

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 }; // 导出 ssmClient

登录后复制

3. 配置 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 强大的模块模拟功能，构建出更健壮、更可靠的单元测试。

以上就是Vitest Mock 在 CommonJS 环境中不生效的解决方案的详细内容，更多请关注php中文网其它相关文章！