Writing Meaningful Unit Tests for Custom Hooks

Why Unit Test Custom Hooks?

Look, we all know testing is important. But sometimes, when you’re deep in the React flow, building out those slick custom hooks, it feels like an extra step, right? You think, “It’s just a hook, it’s not that complicated.” Wrong. Custom hooks are often the heart of your component logic. They encapsulate state, side effects, and complex behaviors. If that logic is flawed, your whole app can feel it. Good unit tests give you confidence that your hook works exactly as intended, making refactoring a breeze and preventing regressions.

What Makes a Good Hook Test?

A good unit test for a custom hook should be:

Focused: Test one specific piece of behavior at a time.
Independent: Each test should run without depending on others.
Repeatable: Tests should yield the same result every time.
Fast: Unit tests should run quickly to provide rapid feedback.
Readable: Clear and easy to understand what’s being tested.

Setting Up Your Test Environment

For React hooks, the gold standard is @testing-library/react. It provides utilities that let you interact with your components and hooks in a way that closely resembles how a user would interact with them, without relying on implementation details. You’ll also need a testing framework like Jest.

First, make sure you have the necessary packages installed:

1
npm install --save-dev @testing-library/react @testing-library/jest-dom jest

Then, you’ll want to configure Jest to use @testing-library/jest-dom for helpful DOM assertion matchers.

Testing Simple State Logic

Let’s start with a basic hook that manages a counter.

useCounter.js

1
import { useState, useCallback } from 'react';
2

3
export function useCounter(initialValue = 0) {
4
  const [count, setCount] = useState(initialValue);
5

6
  const increment = useCallback(() => {
7
    setCount(prevCount => prevCount + 1);
8
  }, []);
9

10
  const decrement = useCallback(() => {
11
    setCount(prevCount => prevCount - 1);
12
  }, []);
13

14
  const reset = useCallback(() => {
15
    setCount(initialValue);
16
  }, [initialValue]);
17

18
  return { count, increment, decrement, reset };
19
}

Now, let’s test it. The key here is the renderHook utility from @testing-library/react. It allows you to render a custom hook and interact with its return values.

useCounter.test.js

1
import { renderHook, act } from '@testing-library/react';
2
import { useCounter } from './useCounter';
3

4
describe('useCounter', () => {
5
  test('should initialize with a default value', () => {
6
    const { result } = renderHook(useCounter);
7
    expect(result.current.count).toBe(0);
8
  });
9

10
  test('should initialize with a provided value', () => {
11
    const { result } = renderHook(() => useCounter(10));
12
    expect(result.current.count).toBe(10);
13
  });
14

15
  test('should increment the count', () => {
16
    const { result } = renderHook(() => useCounter(5));
17

18
    // Use 'act' for state updates
19
    act(() => {
20
      result.current.increment();
21
    });
22

23
    expect(result.current.count).toBe(6);
24
  });
25

26
  test('should decrement the count', () => {
27
    const { result } = renderHook(() => useCounter(5));
28

29
    act(() => {
30
      result.current.decrement();
31
    });
32

33
    expect(result.current.count).toBe(4);
34
  });
35

36
  test('should reset the count to the initial value', () => {
37
    const { result } = renderHook(() => useCounter(7));
38

39
    act(() => {
40
      result.current.increment();
41
      result.current.increment();
42
    });
43
    expect(result.current.count).toBe(9);
44

45
    act(() => {
46
      result.current.reset();
47
    });
48
    expect(result.current.count).toBe(7);
49
  });
50

51
  test('should reset the count to the initial value when initialValue changes', () => {
52
    const { result, rerender } = renderHook(({ initialValue }) => useCounter(initialValue), {
53
      initialProps: { initialValue: 5 },
54
    });
55

56
    act(() => {
57
      result.current.increment();
58
    });
59
    expect(result.current.count).toBe(6);
60

61
    // Rerender with new props
62
    rerender({ initialValue: 10 });
63
    // Note: reset would use the NEW initialValue of 10 if called now.
64
    // We are testing here that the hook correctly reflects the new initialValue state.
65
    expect(result.current.count).toBe(10); // The hook re-initializes because initialValue changed
66

67
    act(() => {
68
      result.current.reset();
69
    });
70
    expect(result.current.count).toBe(10);
71
  });
72
});

Testing Hooks with Side Effects (API Calls)

Testing hooks that involve side effects, like fetching data, requires a bit more setup, usually involving mocking. We’ll use jest.fn() to mock asynchronous functions.

useFetchData.js

1
import { useState, useEffect } from 'react';
2

3
export function useFetchData(url) {
4
  const [data, setData] = useState(null);
5
  const [loading, setLoading] = useState(true);
6
  const [error, setError] = useState(null);
7

8
  useEffect(() => {
9
    const fetchData = async () => {
10
      try {
11
        setLoading(true);
12
        setError(null);
13
        const response = await fetch(url);
14
        if (!response.ok) {
15
          throw new Error(`HTTP error! status: ${response.status}`);
16
        }
17
        const result = await response.json();
18
        setData(result);
19
      } catch (err) {
20
        setError(err);
21
      } finally {
22
        setLoading(false);
23
      }
24
    };
25

26
    fetchData();
27
  }, [url]); // Re-run effect if URL changes
28

29
  return { data, loading, error };
30
}

useFetchData.test.js

We need to mock the global fetch API.

1
import { renderHook, act } from '@testing-library/react';
2
import { useFetchData } from './useFetchData';
3

4
// Mock the global fetch API
5
const mockFetch = jest.fn();
6
global.fetch = mockFetch;
7

8
describe('useFetchData', () => {
9
  beforeEach(() => {
10
    // Reset the mock before each test
11
    mockFetch.mockClear();
12
  });
13

14
  test('should fetch data and update state', async () => {
15
    const mockData = { message: 'Success!' };
16
    mockFetch.mockResolvedValueOnce({
17
      ok: true,
18
      json: async () => mockData,
19
    });
20

21
    const { result, waitForNextUpdate } = renderHook(() => useFetchData('/api/data'));
22

23
    expect(result.current.loading).toBe(true);
24
    expect(result.current.data).toBeNull();
25
    expect(result.current.error).toBeNull();
26
    expect(mockFetch).toHaveBeenCalledTimes(1);
27
    expect(mockFetch).toHaveBeenCalledWith('/api/data');
28

29
    // Wait for the async operations (fetch and state updates) to complete
30
    await waitForNextUpdate();
31

32
    expect(result.current.loading).toBe(false);
33
    expect(result.current.data).toEqual(mockData);
34
    expect(result.current.error).toBeNull();
35
  });
36

37
  test('should handle fetch errors', async () => {
38
    const errorMessage = 'Network Error';
39
    mockFetch.mockRejectedValueOnce(new Error(errorMessage));
40

41
    const { result, waitForNextUpdate } = renderHook(() => useFetchData('/api/error'));
42

43
    expect(result.current.loading).toBe(true);
44

45
    await waitForNextUpdate();
46

47
    expect(result.current.loading).toBe(false);
48
    expect(result.current.data).toBeNull();
49
    expect(result.current.error).toBeInstanceOf(Error);
50
    expect(result.current.error.message).toBe(errorMessage);
51
  });
52

53
  test('should handle non-ok HTTP responses', async () => {
54
    mockFetch.mockResolvedValueOnce({
55
      ok: false,
56
      status: 404,
57
      json: async () => ({}), // Some APIs might still return JSON
58
    });
59

60
    const { result, waitForNextUpdate } = renderHook(() => useFetchData('/api/404'));
61

62
    expect(result.current.loading).toBe(true);
63

64
    await waitForNextUpdate();
65

66
    expect(result.current.loading).toBe(false);
67
    expect(result.current.data).toBeNull();
68
    expect(result.current.error).toBeInstanceOf(Error);
69
    expect(result.current.error.message).toBe('HTTP error! status: 404');
70
  });
71

72
  test('should re-fetch if the URL changes', async () => {
73
    const mockData1 = { id: 1 };
74
    const mockData2 = { id: 2 };
75

76
    mockFetch.mockResolvedValueOnce({
77
      ok: true,
78
      json: async () => mockData1,
79
    });
80
    mockFetch.mockResolvedValueOnce({
81
      ok: true,
82
      json: async () => mockData2,
83
    });
84

85
    const { result, rerender, waitForNextUpdate } = renderHook(
86
      ({ url }) => useFetchData(url),
87
      { initialProps: { url: '/api/item/1' } }
88
    );
89

90
    await waitForNextUpdate(); // First fetch completes
91
    expect(result.current.data).toEqual(mockData1);
92
    expect(mockFetch).toHaveBeenCalledTimes(1);
93

94
    // Rerender hook with a new URL
95
    rerender({ url: '/api/item/2' });
96

97
    // Wait for the second fetch to complete
98
    await waitForNextUpdate();
99
    expect(result.current.data).toEqual(mockData2);
100
    expect(mockFetch).toHaveBeenCalledTimes(2);
101
    expect(mockFetch).toHaveBeenCalledWith('/api/item/2');
102
  });
103
});

Key Takeaways

renderHook is your friend: It’s the primary tool for testing custom hooks.
act is mandatory: Always wrap state-updating logic within act to ensure tests behave predictably.
Mock side effects: For async operations or external dependencies, use Jest’s mocking capabilities.
Test behavior, not implementation: Focus on what the hook does, not how it does it internally.

Writing good tests for your custom hooks might seem like extra work upfront, but it pays dividends in stability, maintainability, and developer confidence. Start small, test thoroughly, and you’ll build more robust React applications. Happy testing!