如何在 Vitest 中模拟构造函数以抛出异常

本文介绍在 Vitest 测试中正确模拟 AWS SDK 的 S3Client 构造函数，使其在实例化时抛出指定异常，解决因自动替换原型导致原构造逻辑失效的问题。

本文介绍在 vitest 测试中正确模拟 aws sdk 的 `s3client` 构造函数，使其在实例化时抛出指定异常，解决因自动替换原型导致原构造逻辑失效的问题。

在单元测试中，有时需要验证代码对第三方客户端（如 @aws-sdk/client-s3 的 S3Client）初始化失败的健壮性——例如网络不可达、凭证缺失等场景下是否能正确捕获并处理异常。但直接修改 prototype.constructor（如通过 Object.defineProperty）在 Vitest 中通常无效，因为 Vitest 的 vi.mock() 机制会完全接管模块导出，且 constructor 属性本身不可靠地拦截 new 调用。

✅ 正确做法是：将 S3Client 类本身模拟为一个函数，并在其内部 throw 异常。Vitest 支持 vi.fn().mockImplementation()，其行为与 Jest 高度兼容，可精准控制构造行为：

// 在 test 文件顶部或 setup 文件中import { vi } from 'vitest'vi.mock('@aws-sdk/client-s3', async () => {  // 可选：保留其他未被 mock 的导出（如命令类）  const actual = await vi.importActual<typeof import('@aws-sdk/client-s3')>('@aws-sdk/client-s3')  return {    ...actual,    // 关键：将 S3Client 替换为一个模拟构造函数    S3Client: vi.fn().mockImplementation(function (this: any, ...args: any[]) {      // 注意：使用普通函数（而非箭头函数），以支持 this 绑定和 new 调用      throw new Error('Failed to instantiate S3Client: mocked constructor error')    }),  }})

⚠️ 注意事项：

• 必须使用 普通函数（function () { ... }）而非箭头函数，否则 this 不指向新实例，且 new 调用可能静默失败或行为异常；
• vi.fn().mockImplementation() 拦截的是 new S3Client(...) 的整个构造过程，因此异常会在 new 时立即抛出；
• 若需区分不同调用场景（如首次失败、第二次成功），可结合 mockImplementationOnce() 实现序列化行为；
• 确保 vi.mock() 调用位于 describe 外部或使用 beforeAll，避免 mock 生效时机问题。

✅ 验证示例：

import { S3Client } from '@aws-sdk/client-s3'describe('S3Client instantiation failure handling', () => {  test('should throw when creating S3Client instance', () => {    expect(() => {      new S3Client({ region: 'us-east-1' })    }).toThrow('Failed to instantiate S3Client: mocked constructor error')  })  // 还可验证你的业务逻辑是否正确捕获该错误  test('service should handle S3Client construction failure', async () => {    await expect(async () => {      // 假设 yourService.createBucket() 内部 new S3Client(...)      await yourService.createBucket('test-bucket')    }).rejects.toThrow('Failed to instantiate S3Client')  })})

? 小结：不要试图劫持原型上的 constructor，而应直接 mock 类的导出值本身。这是 Vitest/Jest 官方推荐且最可靠的构造函数异常模拟方式，语义清晰、行为确定、易于维护。