Vitest项目中vi.mock()在测试文件开头失效的问题分析

问题现象

在Vitest测试框架中，当测试文件以vi.mock()调用开头时，会出现模块未被正确mock的情况。具体表现为第一个vi.mock()调用失效，而后续的mock调用则能正常工作。该问题自Vitest 3.0.0版本开始出现，之前的版本不受影响。

问题复现

通过创建一个简单的测试文件可以复现该问题：

// bug.test.js
vi.mock('src/mockmefirst')  // 第一个mock会失效
vi.mock('src/mockmesecond') // 第二个mock正常工作
vi.mock('src/mockmethird')  // 第三个mock正常工作

import { test, expect, vi } from 'vitest'
import * as first from 'src/mockmefirst'
import * as second from 'src/mockmesecond'
import * as third from 'src/mockmethird'

test('测试mock是否生效', () => {
  console.log(first)  // 显示未被mock
  console.log(second) // 显示已被mock
  console.log(third)  // 显示已被mock
  
  expect(vi.isMockFunction(third.third)).toBe(true)
  expect(vi.isMockFunction(second.second)).toBe(true)
  expect(vi.isMockFunction(first.first)).toBe(true) // 这个断言会失败
})

解决方案

将vi.mock()调用放在import语句之后可以解决这个问题：

// good.test.js
import { test, expect, vi } from 'vitest'
import * as first from 'src/mockmefirst'
import * as second from 'src/mockmesecond'
import * as third from 'src/mockmethird'

vi.mock('src/mockmefirst')  // 现在所有mock都能正常工作
vi.mock('src/mockmesecond')
vi.mock('src/mockmethird')

test('测试mock是否生效', () => {
  // 所有断言都会通过
})

技术原理分析

这个问题源于Vitest 3.0.0版本中与Vite 6的SSR(服务器端渲染)转换相关的变更。在底层实现上：

1. Vitest会对测试文件进行转换处理，自动将vi.mock()调用提升到文件顶部
2. 当开发者手动在文件开头放置vi.mock()时，会导致转换后的代码顺序出现问题
3. 具体表现为第一个手动mock调用被放置在自动提升的mock调用之后，导致其失效

通过调试信息可以看到转换后的代码差异：

// 问题代码转换后
vi.mock('src/mockmesecond') // 自动提升
vi.mock('src/mockmethird')  // 自动提升
import * as first from 'src/mockmefirst'
import * as second from 'src/mockmesecond'
import * as third from 'src/mockmethird'
vi.mock('src/mockmefirst')  // 手动mock被放在后面

// 正常代码转换后
vi.mock('src/mockmefirst')  // 自动提升
vi.mock('src/mockmesecond') // 自动提升
vi.mock('src/mockmethird')  // 自动提升
import * as first from 'src/mockmefirst'
import * as second from 'src/mockmesecond'
import * as third from 'src/mockmethird'

最佳实践建议

1. 避免手动在测试文件开头放置vi.mock()调用
2. 将mock调用放在import语句之后，或者使用Vitest的自动mock提升机制
3. 对于需要提前mock的情况，考虑使用vi.doMock()或设置mock工厂函数
4. 在复杂场景下，可以使用vi.hoisted()来明确控制mock的提升行为

该问题已在Vitest的后续版本中得到修复，但了解其背后的原理有助于开发者更好地理解Vitest的mock机制和避免类似问题。