React Intersection Observer 在 Vitest 2 中的测试配置问题解析

问题背景

React Intersection Observer 是一个流行的 React 库，用于检测元素是否进入视口。在测试环境中，该库提供了专门的测试工具函数来模拟 IntersectionObserver 的行为。然而，当开发者从 Vitest 1.6 升级到 2.0 版本时，遇到了测试工具函数无法正确识别 Vitest 环境的问题。

问题现象

升级到 Vitest 2.0 后，开发者会看到如下警告信息：

React Intersection Observer was not configured to handle mocking.
Outside Jest and Vitest, you might need to manually configure it by calling setupIntersectionMocking() and resetIntersectionMocking() in your test setup file.

这个警告表明库无法自动检测到 Vitest 测试环境，即使测试配置中已经正确设置了全局模式（globals: true）。

技术分析

检测机制原理

React Intersection Observer 的测试工具通过检查全局作用域中是否存在 vi（Vitest）或 jest（Jest）对象来判断当前是否处于测试环境。在 Vitest 1.6 中，这一机制工作正常，但在 Vitest 2.0 中出现了问题。

Vitest 2.0 的变化

Vitest 2.0 对测试钩子的执行顺序做了调整，特别是 beforeAll 和 beforeEach 的执行顺序可能与之前版本不同。这导致在 beforeAll 钩子中调用测试工具函数时，库的初始化代码尚未执行。

根本原因

1. 全局作用域检测失效：在非全局模式（globals: false）下，vi 对象不在全局作用域中，导致检测失败。
2. 钩子执行顺序变化：Vitest 2.0 改变了钩子执行顺序，使得在 beforeAll 中调用工具函数时，库的初始化代码尚未完成。

解决方案

推荐方案

1. 使用 setupFiles 配置： 在 vitest.config.ts 中配置 setupFiles，确保测试工具在测试开始前正确初始化：

// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ["vitest.setup.ts"],
  }
});

// vitest.setup.ts
import { setupIntersectionMocking } from "react-intersection-observer/test-utils";
import { vi } from "vitest";
setupIntersectionMocking(vi.fn);

2. 避免在 beforeAll 中使用： 将 mockAllIsIntersecting 等函数调用移到测试用例内部，而不是 beforeAll 钩子中。

替代方案

1. 启用全局模式： 确保 vitest.config.ts 中启用了 globals:

export default defineConfig({
  test: {
    globals: true,
    environment: "happy-dom",
  }
});

2. 使用 fallback 行为： 可以考虑使用库提供的 fallback 行为，当未启用 mock 时自动返回 true:

import { InView } from 'react-intersection-observer';

<InView fallbackInView={true}>
  {/* 内容 */}
</InView>

最佳实践建议

1. 测试工具函数调用时机：

   • 在测试用例内部调用 mockIsIntersecting 等函数
   • 避免在 beforeAll 中调用，因为此时 IntersectionObserver 可能尚未初始化

2. 清理工作： 确保在每个测试结束后重置 mock 状态：

afterEach(() => {
  resetIntersectionMocking();
});

3. 环境检测： 如果必须检测测试环境，建议直接检查 import.meta.vitest 而不是依赖全局变量。

版本兼容性说明

该问题主要影响：

• React Intersection Observer v9.10.3
• Vitest 2.0 及以上版本

在最新版本中（v9.16.0+），该问题已得到修复，开发者可以直接升级库版本解决此问题。

通过理解这些技术细节和解决方案，开发者可以更顺利地在 Vitest 2.0 环境中使用 React Intersection Observer 进行测试，确保测试用例的可靠性和稳定性。