Node.js MVC项目Jest测试mock Service方法失效的问题解决方案

核心根因 #

你遇到的mock穿透问题、最终抛出TypeError: Cannot read property 'findOne' of undefined报错，本质是Controller内部实际调用的SubscriberService实例，和你测试代码中配置了spy的对象不是同一个内存引用。常见触发场景有两个：

• Controller模块内部直接实例化SubscriberService，测试代码单独new的Service实例完全没有被Controller引用，spy配置自然不会生效
• spy操作没有作用在实际注入到Controller的Service实例上，Controller调用的依然是Service的原始方法，最终穿透到未配置mock的Model层触发报错

典型错误实现 #

这是绝大多数新手写Jest单测时的常见错误代码：

// 错误示例代码
const SubscriberService = require('../service/subscriber.service')
const SubscriberController = require('../controller/subscriber.controller')

test('测试getSubscriber接口', async () => {
  // 测试代码独立创建的Service实例
  const mockService = new SubscriberService()
  jest.spyOn(mockService, 'findByUserId').mockResolvedValue({ id: 1 })

  const req = { user: { id: 1 } }
  const res = { json: jest.fn() }
  // Controller内部是自己直接new的Service，根本不会用上面的mockService
  await SubscriberController.getSubscriber(req, res)
})

分架构的正确实现方案 #

方案1：适配依赖注入模式的项目 #

如果你的Controller是通过构造函数接收外部传入的Service实例，按照以下步骤即可实现有效拦截：

• 提前通过jest.mock全量替换目标Service模块，切断对原始依赖的引用
• 创建和注入逻辑完全一致的Service实例，保证和Controller内部持有的实例引用完全一致
• 在该实例上配置spy逻辑，再将实例传入Controller
  示例代码：

// 第一步：全局替换原始Service模块
jest.mock('../service/subscriber.service')
const SubscriberService = require('../service/subscriber.service')
const SubscriberController = require('../controller/subscriber.controller')

test('测试getSubscriber接口', async () => {
  // 第二步：生成和注入逻辑一致的Service实例
  const mockServiceInstance = new SubscriberService()
  // 第三步：在同一个实例上配置方法mock
  jest.spyOn(mockServiceInstance, 'findByUserId').mockResolvedValue({ id: 1, username: 'test_user' })
  // 第四步：将同一个实例注入Controller
  const controller = new SubscriberController(mockServiceInstance)

  // 触发接口执行
  const req = { user: { id: 1 } }
  const res = { json: jest.fn() }
  await controller.getSubscriber(req, res)

  // 校验mock调用与返回结果
  expect(mockServiceInstance.findByUserId).toHaveBeenCalledWith(1)
  expect(res.json).toHaveBeenCalledWith({ code: 0, data: { id: 1 } })
})

方案2：适配CommonJS模块直接引用模式的项目 #

如果你的Controller是在文件内部直接require引入SubscriberService，没有通过外部注入的方式传递实例，不需要单独new对象，直接通过jest的模块替换能力，让Controller require到的就是被拦截的mock对象即可：
示例代码：

// 提前配置模块替换逻辑，和原模块的导出结构完全对齐
jest.mock('../service/subscriber.service', () => ({
  SubscriberService: jest.fn().mockImplementation(() => ({
    findByUserId: jest.fn()
  }))
}))
const SubscriberController = require('../controller/subscriber.controller')
const { SubscriberService } = require('../service/subscriber.service')

test('测试getSubscriber接口', async () => {
  // 获取被Controller模块内部引用的同一个Service实例
  const mockServiceInstance = new SubscriberService()
  // 配置mock返回值
  mockServiceInstance.findByUserId.mockResolvedValue({ id: 1 })

  const req = { user: { id: 1 } }
  const res = { json: jest.fn() }
  await SubscriberController.getSubscriber(req, res)

  expect(mockServiceInstance.findByUserId).toHaveBeenCalledWith(1)
})

避坑要点 #

• 不要将spy配置在Service类的原型对象上，当Controller内部有实例级别的方法缓存时，原型上的mock依然会失效，最稳妥的方式是直接在传入Controller的实际实例上做拦截
• 配置mock时要明确返回值，避免方法返回undefined触发后续链式调用报错
• 每个测试用例执行完成后调用jest.clearAllMocks()，清空所有mock的调用记录与返回配置，避免不同用例之间的逻辑干扰

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