1. 引言
在现代react应用开发中，自定义hook是逻辑复用的强大工具，而react-query（或tanstack query）则极大地简化了数据获取、缓存和同步。当一个自定义hook内部包含多个usequery调用，用于从不同api端点获取数据时，如何有效地进行单元测试成为了一个关键问题。本教程将深入探讨如何使用@testing-library/react-hooks和jest来测试此类复杂场景，并纠正常见的测试误区。
2. 问题分析与常见误区
考虑一个自定义Hook useTest，它通过react-query同时获取测试详情和测试状态：
// TestHook.js
import { useQuery } from "react-query";
import { getTestByUid, getTestStatusesByUid } from "./api"; // 假设API函数在此模块
export const useTest = (uid) => {
const { data: test } = useQuery("test", () => getTestByUid(uid));
const { data: testStatuses } = useQuery("statuses", () => getTestStatusesByUid(uid));
return {
test,
testStatuses
};
};最初的测试尝试可能面临以下问题：
- 测试隔离性不足：如果为每个useQuery调用创建独立的测试用例，并且只在各自的测试中模拟对应的API函数，那么在第二个测试用例中，第一个API函数可能没有被模拟，导致其真实执行或返回undefined，从而影响测试结果。Jest的spyOn在afterEach或beforeEach中未正确清除时，也可能导致跨测试用例的副作用。
- API模拟不完整：当一个Hook依赖多个外部API调用时，在测试该Hook的整体行为时，所有相关的API都应该被模拟。只模拟其中一个会导致其他未模拟的API调用失败或返回非预期值。
- Mock数据结构不正确：useQuery的data属性直接返回API调用的解析值。如果在模拟API时，将模拟值再次包裹在{ data: ... }中（例如Promise.resolve({ data: { name: "secret test" } })），会导致实际的data属性变为{ data: { name: "secret test" } }，而不是预期的{ name: "secret test" }。
3. 解决方案：模块模拟与整合测试
为了解决上述问题，我们推荐以下策略：
3.1 模块级模拟 (Module Mocking)
使用jest.mock()来模拟整个API模块是更简洁、更强大的方法。它允许我们替换模块中的所有导出函数，并在每个测试用例中灵活地设置它们的行为。
// test-hook.test.js
import { renderHook } from '@testing-library/react-hooks';
import { QueryClient, QueryClientProvider } from 'react-query';
import { useTest } from './test-hook';
import * as testApi from './api'; // 导入API模块
import React from 'react';
// 在文件顶部模拟整个API模块
jest.mock('./api'); // 这将使testApi.getTestByUid和testApi.getTestStatusesByUid成为jest mock函数通过jest.mock('./api')，testApi中的所有函数都变成了Jest的模拟函数，我们可以直接使用mockResolvedValue或mockRejectedValue来控制它们的行为，而无需使用spyOn。
3.2 整合测试用例
当一个Hook的目的是组合多个数据源时，通常应该在一个测试用例中验证所有这些数据源是否被正确获取和返回。这不仅提高了测试效率，也更好地反映了Hook的整体功能。
// test-hook.test.js (续)
// ... (之前的导入和jest.mock)
const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: false, // 在测试中禁用重试以避免不必要的等待
},
},
});
const wrapper = ({ children }) => {
return {children} ;
};
describe('useTestHook', () => {
it('should return test details and statuses correctly', async () => {
// 为所有API调用设置模拟返回值
testApi.getTestByUid.mockResolvedValue({ name: 'secret test' });
testApi.getTestStatusesByUid.mockResolvedValue(['in_progress', 'ready_for_approval', 'rejected']);
const { result, waitForNextUpdate } = renderHook(() => useTest('bb450409-d778-4d57-a4b8-70fcfe2087bd'), {
wrapper,
});
// 等待React Query完成数据获取
await waitForNextUpdate();
// 断言Hook返回的所有数据
expect(result.current.test).toEqual({ name: 'secret test' });
expect(result.current.testStatuses).toEqual(['in_progress', 'ready_for_approval', 'rejected']);
});
});3.3 正确的Mock数据结构
如前所述，useQuery的data属性直接包含API的解析值。因此，在模拟API函数时，直接返回期望的数据即可，无需额外包裹：
// 错误示例：
// testApi.getTestByUid.mockResolvedValue({ data: { name: 'secret test' } });
// 导致 result.current.test 为 { data: { name: 'secret test' } }
// 正确示例：
testApi.getTestByUid.mockResolvedValue({ name: 'secret test' });
// 导致 result.current.test 为 { name: 'secret test' }4. 完整的示例代码
4.1 api.js (模拟的API模块)
// api.js
export const getTestByUid = (uid) => {
// 实际应用中会是真实的API调用，这里仅为模拟提供函数签名
return Promise.resolve({ id: uid, name: "real test data" });
};
export const getTestStatusesByUid = (uid) => {
// 实际应用中会是真实的API调用
return Promise.resolve(["active", "completed"]);
};4.2 test-hook.js (自定义Hook)
// test-hook.js
import { useQuery } from "react-query";
import { getTestByUid, getTestStatusesByUid } from "./api";
export const useTest = (uid) => {
const { data: test } = useQuery(["test", uid], () => getTestByUid(uid)); // 推荐使用数组作为queryKey
const { data: testStatuses } = useQuery(["statuses", uid], () => getTestStatusesByUid(uid)); // 推荐使用数组作为queryKey
return {
test,
testStatuses
};
};注意: 在useQuery的queryKey中使用数组["test", uid]是更好的实践，它能确保当uid变化时，react-query能够正确地识别并重新获取数据。
4.3 test-hook.test.js (测试文件)
// test-hook.test.js
import { renderHook } from '@testing-library/react-hooks';
import { QueryClient, QueryClientProvider } from 'react-query';
import { useTest } from './test-hook';
import * as testApi from './api';
import React from 'react';
// 在文件顶部模拟整个API模块
jest.mock('./api');
// 初始化QueryClient，并禁用重试以简化测试
const queryClient = new QueryClient({
defaultOptions: {
queries: {
retry: false,
},
},
});
// 定义一个Wrapper组件，用于为Hook提供React Query上下文
const wrapper = ({ children }) => {
return {children} ;
};
describe('useTestHook', () => {
it('should return test details and statuses correctly for a given UID', async () => {
const mockUid = 'bb450409-d778-4d57-a4b8-70fcfe2087bd';
const mockTestDetails = { id: mockUid, name: 'secret test' };
const mockTestStatuses = ['in_progress', 'ready_for_approval', 'rejected'];
// 设置API函数的模拟返回值
testApi.getTestByUid.mockResolvedValue(mockTestDetails);
testApi.getTestStatusesByUid.mockResolvedValue(mockTestStatuses);
// 渲染自定义Hook
const { result, waitForNextUpdate } = renderHook(() => useTest(mockUid), {
wrapper,
});
// 等待React Query完成数据获取（即promise解析）
await waitForNextUpdate();
// 断言Hook的返回值是否符合预期
expect(result.current.test).toEqual(mockTestDetails);
expect(result.current.testStatuses).toEqual(mockTestStatuses);
// 也可以验证API函数是否被正确调用
expect(testApi.getTestByUid).toHaveBeenCalledTimes(1);
expect(testApi.getTestByUid).toHaveBeenCalledWith(mockUid);
expect(testApi.getTestStatusesByUid).toHaveBeenCalledTimes(1);
expect(testApi.getTestStatusesByUid).toHaveBeenCalledWith(mockUid);
});
it('should handle API errors gracefully (example)', async () => {
const mockUid = 'error-uid';
const errorMessage = 'Failed to fetch test details';
// 模拟一个API调用失败
testApi.getTestByUid.mockRejectedValue(new Error(errorMessage));
testApi.getTestStatusesByUid.mockResolvedValue(['available']); // 另一个API可以成功
const { result, waitForNextUpdate } = renderHook(() => useTest(mockUid), {
wrapper,
});
// 等待数据更新，这里可能需要等待错误状态
await waitForNextUpdate();
// 根据useQuery的错误处理逻辑，可能需要检查result.current.test是否为undefined或检查error对象
// 注意：useQuery的错误会存储在各自的error属性中，这里简化为检查data是否为undefined
expect(result.current.test).toBeUndefined();
expect(result.current.testStatuses).toEqual(['available']); // 另一个API数据依然存在
// 实际项目中，你可能还会断言 error 对象
// expect(result.current.error).toBeDefined();
});
});5. 注意事项与最佳实践
- 测试隔离：确保每个测试用例都是独立的。使用jest.mock后，可以在每个it块内部重置或重新设置模拟函数的行为，以避免测试之间的相互影响。mockResolvedValue在每次调用时都会设置新的行为。
- 全面模拟：如果Hook依赖多个外部函数，请确保所有这些外部函数都在测试中被模拟。否则，未模拟的函数可能会导致实际的网络请求或意外的行为。
- queryKey的重要性：在useQuery中，queryKey是识别和缓存查询的关键。当Hook的参数（如uid）作为queryKey的一部分时，确保在测试中传递相同的参数，以便react-query能够正确匹配查询。
- 错误处理：除了成功获取数据的场景，也应该测试API调用失败时的Hook行为，例如useQuery的error属性是否被正确设置，以及UI是否能相应地处理错误状态。
- waitForNextUpdate：@testing-library/react-hooks提供的waitForNextUpdate是等待异步操作（如react-query的数据获取）完成的关键。它确保在断言之前，Hook的状态已经更新。
- 依赖版本：请确保使用的react-query和@testing-library/react-hooks版本兼容。示例中使用的版本为"react-query": "^3.34.7"和"@testing-library/react-hooks": "^8.0.1"。
6. 总结
通过采用模块级模拟、整合测试用例以及确保正确的Mock数据结构，我们可以高效且准确地测试包含多个react-query调用的自定义React Hook。这种方法不仅提高了测试的可靠性，也使测试代码更易于维护和理解，从而为构建健壮的React应用程序奠定基础。
