从Jest迁移至Vitest后TanStack React Query状态更新异常求助

不少开发者从Jest切换到Vitest后，都会碰到TanStack React Query的useQuery钩子状态更新异常的情况——初始触发后loading设为true，但查询函数明明成功拿到结果，loading却一直不切换，只有手动跑完全部计时器（比如vi.runAllTimers()）才能恢复正常。

下面是几个常见的原因和解决办法：

1. 计时器模拟的差异 #

Vitest的假计时器默认行为和Jest不一样，而React Query内部靠时间调度来更新状态。如果测试里开了假计时器但没正确推进，状态就会卡着不动。

• 如果你不需要假计时器，直接用真实时间测试就行，配合waitFor等待状态更新：

  test('useQuery能正常切换加载状态', async () => {
    render(<YourComponent />);
    // 等待加载完成的元素出现
    await waitFor(() => {
      expect(screen.getByText('数据加载完成')).toBeInTheDocument();
    });
  });
  

• 要是必须用假计时器，记得在查询执行后推进所有计时器：

  test('假计时器下useQuery状态正常更新', async () => {
    vi.useFakeTimers();
    render(<YourComponent />);
    // 推进计时器让查询流程走完
    vi.runAllTimers();
    await waitFor(() => {
      expect(screen.queryByText('加载中')).not.toBeInTheDocument();
    });
    // 用完记得切回真实计时器
    vi.useRealTimers();
  });
  

2. React Query的测试配置没跟上 #

迁移后可能没重新配置测试用的QueryClient，默认的重试、缓存设置可能和Vitest的环境不兼容。可以在测试里自定义QueryClient，禁用重试、缩短缓存时间：

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// 配置测试专用的QueryClient
const testQueryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false, // 关掉重试，避免测试里额外等待
      staleTime: 0,
    },
  },
});

// 包装组件用的Provider
const TestWrapper = ({ children }) => (
  <QueryClientProvider client={testQueryClient}>{children}</QueryClientProvider>
);

test('useQuery状态更新正常', async () => {
  render(<YourComponent />, { wrapper: TestWrapper });
  await waitFor(() => {
    expect(screen.getByText('加载完成')).toBeInTheDocument();
  });
});

3. 异步断言的姿势不对 #

Vitest对异步操作的处理和Jest略有区别，别用同步断言去等状态变化，一定要用waitFor或者findBy*这类异步查询方法，确保等React状态更新完成后再断言。

内容的提问来源于stack exchange，提问作者ramesh