解决Vitest 3中performance.now()计时器模拟失效的终极方案
项目地址: https://gitcode.com/GitHub_Trending/vi/vitest 你是否遇到过这样的情况：在测试包含performance.now()的代码时，明明已经使用了vi.useFakeTimers()，但计时器却完全不受控制？这不是你的代码有问题，而是Vitest 3在处理高精度计时器时存在的特殊场景。本文将深入分析这一问题的根源，并提供三种经过验证的解决方案，帮助你在测试中精准控制时间流逝。
问题现象与技术背景
当使用Vitest的计时器模拟功能时，你可能会发现一个奇怪的现象：setTimeout和setInterval能够被正常模拟，但performance.now()却始终返回真实时间戳。这种不一致性会导致依赖高精度计时的代码测试失败，例如动画帧计算、性能监控函数等关键逻辑。
Vitest的计时器模拟系统基于@sinonjs/fake-timers实现，该库主要模拟了setTimeout、setInterval等传统计时器API，但没有覆盖HTML5新增的performance.now()方法。这一设计选择在Vitest的官方文档中虽未明确说明，但通过分析Mocking Timers文档和源码实现可以得到验证。
三种解决方案及其适用场景
方案一：手动模拟performance对象（快速修复）
最简单直接的方法是使用vi.stubGlobal()手动替换全局performance对象：
beforeEach(() => {
vi.useFakeTimers();
// 模拟performance.now()方法
vi.stubGlobal('performance', {
now: vi.fn(() => vi.now())
});
});
afterEach(() => {
vi.useRealTimers();
vi.unstubAllGlobals(); // 重要：恢复原始performance对象
});
it('should mock performance.now() correctly', () => {
const start = performance.now();
vi.advanceTimersByTime(100);
const end = performance.now();
expect(end - start).toBe(100); // 断言成立
});
这种方法的优势在于实现简单，适用于单文件测试或小型项目。但需要注意，该方案会全局替换performance对象，可能影响其他依赖该对象的API（如performance.mark()）。
方案二：使用专用模拟模块（推荐方案）
对于需要在多个测试文件中复用的场景，创建一个专用的计时器模拟模块是更优选择：
// test/mocks/performance.ts
export function mockPerformanceNow() {
const originalPerformance = global.performance;
beforeEach(() => {
vi.useFakeTimers();
global.performance = {
...originalPerformance,
now: vi.fn(() => vi.now())
} as Performance;
});
afterEach(() => {
vi.useRealTimers();
global.performance = originalPerformance;
});
}
// 在测试文件中使用
import { mockPerformanceNow } from '../mocks/performance';
describe('Timer-sensitive code', () => {
mockPerformanceNow();
it('should calculate elapsed time correctly', () => {
// 测试逻辑...
});
});
该方案通过测试上下文隔离确保了模拟的安全性，同时保持了performance对象的其他方法可用。推荐在中型项目中使用，特别是当测试需要同时验证普通计时器和高精度计时器时。
方案三：自定义计时器模拟实现（高级场景）
对于复杂的测试场景，例如需要模拟时间流速变化或与其他API协同工作时，可以实现更精细的控制逻辑：
class MockPerformance {
private startTime: number;
constructor() {
this.startTime = Date.now();
}
now() {
return vi.isFakeTimersActive()
? vi.now() - this.startTime
: performance.now();
}
// 可以添加其他需要模拟的performance方法
}
// 在测试中使用
beforeEach(() => {
vi.useFakeTimers();
vi.stubGlobal('performance', new MockPerformance());
});
这种方式适合大型项目和框架级测试，通过自定义模拟类可以精确控制时间行为，甚至模拟时间暂停、加速等特殊场景。
调试与验证技巧
为确保计时器模拟按预期工作，建议在测试中添加以下验证步骤：
it('should verify timer mocking setup', () => {
// 验证传统计时器是否被模拟
const setTimeoutSpy = vi.spyOn(global, 'setTimeout');
// 验证performance.now()是否被模拟
const performanceNowSpy = vi.spyOn(performance, 'now');
vi.advanceTimersByTime(100);
expect(setTimeoutSpy).toHaveBeenCalledTimes(0); // 没有真实计时器调用
expect(performanceNowSpy).toHaveBeenCalled(); // 模拟方法被调用
});
此外，使用Vitest的调试工具可以更直观地观察时间流动：
vitest --inspect-brk --no-file-parallelism
通过Vitest调试指南中介绍的Chrome DevTools连接方式，你可以在测试执行过程中实时查看vi.now()和performance.now()的返回值，精确判断模拟是否生效。
最佳实践与注意事项
-
清理工作至关重要：始终在
afterEach中调用vi.useRealTimers()和vi.unstubAllGlobals()，避免测试间的计时器状态污染。 -
谨慎使用全局模拟：如非必要，优先选择局部模拟而非全局替换，特别是在浏览器模式测试中，全局对象的变更可能导致意外行为。
-
版本兼容性：本文方案适用于Vitest 3.x版本，如果你使用的是2.x版本，可能需要调整
vi.stubGlobal为vi.stub。 -
性能影响：自定义计时器模拟可能会使测试执行时间增加约10-15%，对于大型测试套件，建议仅在必要的测试文件中应用模拟。
总结与展望
处理performance.now()模拟问题的核心在于理解Vitest计时器系统的覆盖范围。通过本文介绍的三种方案，你可以根据项目规模和测试复杂度选择最适合的实现方式：
- 快速修复：使用
vi.stubGlobal直接替换 - 标准方案：创建专用模拟模块
- 高级场景：实现自定义Performance类
随着Web API的不断发展，未来Vitest可能会原生支持performance.now()模拟。在此之前，这些解决方案可以帮助你应对大多数计时相关的测试挑战。如果你在实施过程中遇到问题，可以参考Vitest常见错误文档或在社区寻求帮助。
记住，良好的测试不仅验证功能正确性，更要模拟真实世界的各种边缘情况——而时间，正是最微妙也最关键的那一种。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
