React Hooks 测试指南：testing-library/react-hooks-testing-library 基础用法
项目地址: https://gitcode.com/gh_mirrors/re/react-hooks-testing-library 引言：为什么需要专门的 Hooks 测试工具？
在 React 开发中，自定义 Hooks（自定义钩子）已经成为代码复用的重要手段。然而，当尝试直接测试这些 Hooks 时，开发者经常会遇到一个令人沮丧的错误：
Invariant Violation: Hooks can only be called inside the body of a function component.
这个错误意味着 Hooks 只能在函数组件体内调用，这给测试带来了巨大挑战。传统的解决方案是创建一个包装组件来测试 Hook，但这会导致测试代码冗长、难以维护，并且无法准确模拟真实的 Hook 使用场景。
@testing-library/react-hooks 应运而生，它提供了一个简单而完整的 React Hooks 测试工具集，鼓励良好的测试实践，让开发者能够专注于测试 Hook 的逻辑而不是包装组件的实现细节。
快速开始：安装与配置
安装依赖
# 使用 npm
npm install --save-dev @testing-library/react-hooks
# 使用 yarn
yarn add --dev @testing-library/react-hooks
安装对等依赖
# 安装 React（版本需 ≥ 16.9.0）
npm install react@^16.9.0
# 安装渲染器（二选一）
npm install --save-dev react-test-renderer@^16.9.0 # 推荐，支持 React Native
# 或
npm install --save-dev react-dom@^16.9.0
环境配置说明
核心 API 详解
renderHook - 渲染 Hook 的核心方法
renderHook 是库的核心函数，它创建一个测试组件来调用你提供的回调函数，包括其中调用的所有 Hooks。
基本语法：
function renderHook(callback: (props?: any) => any, options?: RenderHookOptions): RenderHookResult
返回值结构
interface RenderHookResult {
result: {
all: Array<any> // 所有历史返回值
current: any // 最新返回值
error: Error // 错误信息（如果有）
}
rerender: (newProps?: any) => void // 重新渲染函数
unmount: () => void // 卸载函数
hydrate: () => void // 水合函数（SSR）
...asyncUtils // 异步工具函数
}
基础用法实战
1. 测试简单状态 Hook
让我们从一个简单的计数器 Hook 开始：
// useCounter.js
import { useState, useCallback } from 'react'
export default function useCounter(initialValue = 0) {
const [count, setCount] = useState(initialValue)
const increment = useCallback(() => setCount(x => x + 1), [])
const decrement = useCallback(() => setCount(x => x - 1), [])
const reset = useCallback(() => setCount(initialValue), [initialValue])
return { count, increment, decrement, reset }
}
对应的测试用例：
// useCounter.test.js
import { renderHook, act } from '@testing-library/react-hooks'
import useCounter from './useCounter'
describe('useCounter', () => {
test('should initialize with default value', () => {
const { result } = renderHook(() => useCounter())
expect(result.current.count).toBe(0)
expect(typeof result.current.increment).toBe('function')
expect(typeof result.current.decrement).toBe('function')
expect(typeof result.current.reset).toBe('function')
})
test('should increment counter', () => {
const { result } = renderHook(() => useCounter(5))
act(() => {
result.current.increment()
})
expect(result.current.count).toBe(6)
})
test('should decrement counter', () => {
const { result } = renderHook(() => useCounter(10))
act(() => {
result.current.decrement()
})
expect(result.current.count).toBe(9)
})
test('should reset to initial value', () => {
const { result } = renderHook(() => useCounter(100))
// 先改变状态
act(() => {
result.current.increment()
result.current.increment()
})
expect(result.current.count).toBe(102)
// 重置
act(() => {
result.current.reset()
})
expect(result.current.count).toBe(100)
})
})
2. 处理 Props 变化
当 Hook 依赖外部 props 时，需要使用 rerender 方法：
// useDynamicValue.js
import { useState, useEffect } from 'react'
export default function useDynamicValue(initialValue) {
const [value, setValue] = useState(initialValue)
useEffect(() => {
setValue(initialValue)
}, [initialValue])
return value
}
测试 Props 变化：
// useDynamicValue.test.js
import { renderHook } from '@testing-library/react-hooks'
import useDynamicValue from './useDynamicValue'
test('should update value when initialValue changes', () => {
const { result, rerender } = renderHook(
({ initialValue }) => useDynamicValue(initialValue),
{ initialProps: { initialValue: 'first' } }
)
expect(result.current).toBe('first')
// 更新 props
rerender({ initialValue: 'second' })
expect(result.current).toBe('second')
})
3. 使用 Wrapper 提供 Context
对于依赖 Context 的 Hooks：
// useTheme.js
import { useContext } from 'react'
import { ThemeContext } from './ThemeContext'
export default function useTheme() {
const theme = useContext(ThemeContext)
return theme
}
测试 Context 相关的 Hook：
// useTheme.test.js
import { renderHook } from '@testing-library/react-hooks'
import useTheme from './useTheme'
import { ThemeContext, ThemeProvider } from './ThemeContext'
test('should return theme from context', () => {
const wrapper = ({ children }) => (
<ThemeProvider value="dark">{children}</ThemeProvider>
)
const { result } = renderHook(() => useTheme(), { wrapper })
expect(result.current).toBe('dark')
})
异步 Hook 测试
处理异步操作
// useAsyncData.js
import { useState, useEffect } from 'react'
export default function useAsyncData(url) {
const [data, setData] = useState(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)
useEffect(() => {
const fetchData = async () => {
try {
setLoading(true)
const response = await fetch(url)
const result = await response.json()
setData(result)
} catch (err) {
setError(err.message)
} finally {
setLoading(false)
}
}
fetchData()
}, [url])
return { data, loading, error }
}
异步测试示例：
// useAsyncData.test.js
import { renderHook, act } from '@testing-library/react-hooks'
import useAsyncData from './useAsyncData'
// 模拟 fetch
global.fetch = jest.fn()
describe('useAsyncData', () => {
beforeEach(() => {
fetch.mockClear()
})
test('should handle successful data fetch', async () => {
const mockData = { id: 1, name: 'Test' }
fetch.mockResolvedValueOnce({
json: async () => mockData
})
const { result, waitForNextUpdate } = renderHook(() =>
useAsyncData('/api/data')
)
// 初始状态
expect(result.current.loading).toBe(true)
expect(result.current.data).toBe(null)
expect(result.current.error).toBe(null)
// 等待更新
await waitForNextUpdate()
// 最终状态
expect(result.current.loading).toBe(false)
expect(result.current.data).toEqual(mockData)
expect(result.current.error).toBe(null)
})
test('should handle fetch error', async () => {
const errorMessage = 'Network error'
fetch.mockRejectedValueOnce(new Error(errorMessage))
const { result, waitForNextUpdate } = renderHook(() =>
useAsyncData('/api/data')
)
await waitForNextUpdate()
expect(result.current.loading).toBe(false)
expect(result.current.data).toBe(null)
expect(result.current.error).toBe(errorMessage)
})
})
高级异步工具
waitFor 的使用
test('should wait for specific condition', async () => {
const { result, waitFor } = renderHook(() => useSomeAsyncHook())
await waitFor(() => {
expect(result.current.isReady).toBe(true)
})
// 或者使用更简洁的断言
await waitFor(() => expect(result.current.data).toBeDefined())
})
waitForValueToChange 的使用
test('should wait for value change', async () => {
const { result, waitForValueToChange } = renderHook(() => useSomeHook())
// 触发某些异步操作
act(() => {
result.current.startAsyncOperation()
})
// 等待特定值发生变化
await waitForValueToChange(() => result.current.status)
expect(result.current.status).toBe('completed')
})
错误处理与调试
测试错误边界
// useErrorThrowingHook.js
import { useState } from 'react'
export default function useErrorThrowingHook() {
const [value, setValue] = useState(null)
const triggerError = () => {
throw new Error('Test error')
}
return { value, triggerError }
}
错误测试：
// useErrorThrowingHook.test.js
import { renderHook, act } from '@testing-library/react-hooks'
import useErrorThrowingHook from './useErrorThrowingHook'
test('should catch errors thrown in hook', () => {
const { result } = renderHook(() => useErrorThrowingHook())
act(() => {
// 这个操作会抛出错误
expect(() => result.current.triggerError()).toThrow('Test error')
})
// 错误会被捕获并存储在 result.error 中
expect(result.error).toEqual(Error('Test error'))
})
最佳实践与常见陷阱
✅ 推荐做法
- 始终使用
act包装状态更新 - 合理使用异步工具函数处理异步操作
- 为 Context 相关的 Hooks 提供 wrapper
- 清理测试环境，避免测试间相互影响
❌ 常见错误
// 错误示例：忘记使用 act
test('should not do this', () => {
const { result } = renderHook(() => useCounter())
// 错误：没有用 act 包装状态更新
result.current.increment() // ❌
expect(result.current.count).toBe(1)
})
// 正确示例
test('should do this correctly', () => {
const { result } = renderHook(() => useCounter())
act(() => {
result.current.increment() // ✅
})
expect(result.current.count).toBe(1)
})
性能优化建议
React 18+ 兼容性说明
从 React 18 开始，renderHook API 已经作为官方功能加入到 @testing-library/react 中：
// React 18+ 推荐用法
import { renderHook, act } from '@testing-library/react'
// 而不是
import { renderHook, act } from '@testing-library/react-hooks'
迁移建议：
- 新项目直接使用
@testing-library/react - 现有项目可逐步迁移
- API 基本保持一致，迁移成本低
总结
@testing-library/react-hooks 为 React Hooks 测试提供了强大而灵活的解决方案。通过本文的介绍，你应该已经掌握了：
- ✅ 库的安装和基本配置
- ✅
renderHook和act的核心用法 - ✅ 同步和异步 Hooks 的测试策略
- ✅ Context 和 Props 变化的处理方法
- ✅ 错误处理和调试技巧
- ✅ 最佳实践和常见陷阱避免
记住，良好的测试不仅仅是验证代码正确性，更是设计良好 API 的体现。通过为你的自定义 Hooks 编写全面的测试，你不仅确保了代码质量，也为其他开发者提供了清晰的使用示例。
开始为你的下一个 React 项目编写可靠的 Hooks 测试吧！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
