关于通过实际HTTP请求调用时Sinon Stub不生效的技术咨询

这个问题我之前帮好几个开发者踩过坑，核心原因大多和模块加载的实例不一致或者Stub时机不对有关，下面给你拆解几个实用的解决方向：

1. 先确认Stub的时机是否搞反了 #

很多人会犯这个低级错误：先启动了Express/Koa这类HTTP服务器，然后才去Stub目标函数。这时候应用早就加载完目标模块并缓存了函数引用，后续的Stub根本影响不到已经运行的服务器实例。

正确的操作顺序必须是：

• 第一步：Stub目标函数
• 第二步：导入并启动HTTP服务器
• 第三步：发起HTTP请求测试

举个代码对比的例子：

// ❌ 错误顺序：先启动服务器再Stub
const app = require('./app');
const request = require('supertest');
const sinon = require('sinon');
const foo = require('./foo');

test('HTTP请求测试', async () => {
  sinon.stub(foo, 'bar').returns('stubbed结果');
  await request(app).get('/test-endpoint'); // 这里app已经加载过foo，Stub完全不生效
});

// ✅ 正确顺序：先Stub再加载服务器
const request = require('supertest');
const sinon = require('sinon');

test('HTTP请求测试', async () => {
  const foo = require('./foo');
  sinon.stub(foo, 'bar').returns('stubbed结果');
  const app = require('./app'); // 现在app加载的foo已经被Stub处理过了
  await request(app).get('/test-endpoint');
});

2. 检查模块引用是否存在"副本"问题 #

如果你的测试代码里Stub的是测试文件单独导入的模块，而应用代码里用的是另一个模块实例（虽然Node.js有模块缓存，但如果路径不一致或者有别名，可能会出现这种情况），那Stub肯定不生效。

比如测试里写const foo = require('../src/foo')，但应用里写const foo = require('./foo')，如果目录结构导致路径解析后不是同一个文件，就会产生两个独立的模块实例。解决方法是：确保测试和应用使用完全一致的模块导入路径，或者用proxyquire这类工具直接替换应用依赖的模块。

用proxyquire的示例：

const proxyquire = require('proxyquire');
const sinon = require('sinon');
const request = require('supertest');

test('用proxyquire替换模块', async () => {
  // 创建Stub函数
  const barStub = sinon.stub().returns('stubbed结果');
  // 加载app时，把依赖的./foo替换成我们的Stub
  const app = proxyquire('./app', {
    './foo': { bar: barStub }
  });
  // 发起请求
  await request(app).get('/test-endpoint');
  // 验证Stub是否被调用
  expect(barStub.called).toBe(true);
});

3. 排查是否存在函数引用被重新赋值的情况 #

如果应用代码里把目标函数赋值给了本地变量，然后调用的是这个本地变量，那你Stub模块导出的函数是没用的。

比如应用代码里这么写：

// ❌ 这种写法会导致Stub失效
const { bar } = require('./foo');
// 把bar赋值给本地变量myBar
const myBar = bar;

async function handler(req, res) {
  // 调用的是本地变量myBar，不是模块导出的bar
  const result = await myBar();
  res.send(result);
}

解决方法要么修改应用代码，直接调用模块导出的函数（比如require('./foo').bar()），要么Stub本地变量所在的模块里的引用（这时候可能需要用rewire或者proxyquire来修改私有变量）。

4. ES模块（ESM）环境下的特殊处理 #

如果你的项目用的是import/export而不是CommonJS的require，Sinon的Stub方式需要调整，因为ESM的模块缓存和加载机制和CommonJS不同。

这种情况下，你可以尝试用sinon.stub结合动态导入，或者使用esmock这类专门针对ESM的模块替换工具。比如：

import { test } from 'vitest';
import sinon from 'sinon';
import request from 'supertest';
import esmock from 'esmock';

test('ESM环境下的Stub', async () => {
  const barStub = sinon.stub().returns('stubbed结果');
  // 用esmock替换模块
  const app = await esmock('./app.js', {
    './foo.js': { bar: barStub }
  });
  await request(app).get('/test-endpoint');
  expect(barStub.called).toBe(true);
});

5. 检查Stub的作用域和恢复机制 #

有时候Stub没生效是因为之前的测试用例恢复了Stub，或者Stub的作用域不对。建议用sinon.createSandbox()来管理每个测试用例的Stub，确保测试之间相互隔离，并且在测试后自动恢复原始函数：

const sinon = require('sinon');
const request = require('supertest');

let sandbox;

beforeEach(() => {
  // 每个测试前创建新的sandbox
  sandbox = sinon.createSandbox();
});

afterEach(() => {
  // 每个测试后恢复所有Stub
  sandbox.restore();
});

test('用sandbox管理Stub', async () => {
  const foo = require('./foo');
  sandbox.stub(foo, 'bar').returns('stubbed结果');
  const app = require('./app');
  await request(app).get('/test-endpoint');
});

按照这几个方向排查，基本能解决大部分HTTP请求下Stub不生效的问题。

内容的提问来源于stack exchange，提问作者Robert C