React Native Testing Library 中 waitFor 与并发渲染的兼容性问题分析

问题背景

在使用 React Native Testing Library (RNTL) 进行测试时，开发者在升级到 v13 版本后遇到了一个特殊问题：所有依赖 waitFor 或 findBy 查询的测试用例在启用并发渲染模式(concurrentRoot: true)时会失败，而在传统渲染模式下(concurrentRoot: false)则能正常通过。

现象描述

测试用例中常见的异步等待模式突然失效，具体表现为：

• 使用 waitFor 或 findBy 查询时，即使组件状态已更新，测试也无法检测到预期的 DOM 变化
• 当 Jest 的计时器被推进时(advanceTimersByTime)，UI 不再更新
• 手动在 waitFor 内部包裹 act 可以临时解决问题，但这并非推荐做法

根本原因分析

经过深入调查，发现问题根源在于测试环境的初始化顺序：

1. 计时器模拟时机不当：当 jest.useFakeTimers() 在测试文件模块导入阶段就被调用时，会导致 RNTL 和 react-test-renderer 在初始化时就已经处于模拟计时器环境下

2. 并发渲染的特殊性：React 的并发渲染模式对任务调度和时序更加敏感，当核心计时函数被过早模拟时，会影响渲染任务的正确调度

3. 测试渲染器行为差异：react-test-renderer 在导入时会缓存全局计时函数引用，如果此时计时器已被模拟，后续所有时间相关操作都会使用模拟实现

解决方案

正确的做法是调整测试初始化流程：

1. 延迟计时器模拟：将 jest.useFakeTimers() 调用移至测试运行前的 beforeAll 钩子中，确保核心模块已完成初始化

2. 保持测试环境纯净：避免在模块导入阶段执行任何可能影响全局环境的操作

3. 合理使用渲染选项：在 React 19 发布前，如非必要可暂时使用 concurrentRoot: false 作为过渡方案

最佳实践建议

1. 测试初始化顺序：

   • 先导入所有必要模块
   • 然后在 beforeAll 或测试用例中配置测试环境
   • 最后执行测试逻辑

2. 异步测试注意事项：

   • 对于并发渲染组件，确保所有状态更新都被正确处理
   • 考虑增加适当的延迟或等待条件
   • 避免过度依赖具体实现细节

3. 版本兼容性：

   • 保持 RNTL 与 React Native 版本的匹配
   • 关注 React 19 对并发渲染的改进
   • 定期更新测试工具链

总结

这个问题揭示了测试环境中初始化顺序的重要性，特别是在涉及时间模拟和并发渲染的复杂场景下。通过调整计时器模拟的时机，开发者可以确保测试工具和渲染器能够正确协作，从而获得准确的测试结果。这也提醒我们在升级测试工具链时，需要仔细评估现有测试用例与新特性的兼容性。