Testing Custom Hooks in Isolation: renderHook in Practice

1. Why custom hooks need their own tests

A custom hook often encapsulates complex logic: debouncing, form validation, pagination, or managing WebSocket state. If such a hook is only tested indirectly through a component that uses it, two completely different responsibilities blend together in a single test: the hook's correct behavior and the component's correct rendering. When the test fails, it is initially unclear which of the two layers is the cause.

Testing custom hooks directly solves this problem by running the hook in isolation from any concrete UI. renderHook from @testing-library/react internally creates a minimal host component that stays invisible to the test, and runs the hook inside it. The hook's return value is made accessible via result.current, so assertions can be written directly against the hook's values and functions, without any visible component needing to be rendered.

The practical benefit shows up especially for reusable custom hooks used across multiple components. An isolated test for useDebounce or usePagination covers the logic once, instead of testing it indirectly, again and again, in every consuming component. This significantly reduces test duplication and makes the cause of a failure immediately localizable.

2. renderHook: basics and return values

renderHook(callback, options) takes a function that calls the hook under test, and returns an object with result, rerender and unmount. result.current always contains the most recent return value of the hook after the last render. This structure mirrors exactly how a hook would be used inside a real component, just without any visible markup around it.

An important detail: the custom hook gets re-executed on every call to rerender(), exactly like a component on every render cycle. This makes it possible to simulate prop changes by calling rerender with new arguments, which then get used on the next call of the hook callback.

// useCounter.ts — the custom hook under test
import { useState, useCallback } from 'react'

export function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue)
  const increment = useCallback(() => setCount((c) => c + 1), [])
  const decrement = useCallback(() => setCount((c) => c - 1), [])
  const reset = useCallback(() => setCount(initialValue), [initialValue])

  return { count, increment, decrement, reset }
}

// useCounter.test.ts — isolated test with renderHook
import { renderHook, act } from '@testing-library/react'
import { useCounter } from './useCounter'

test('increments and decrements the counter', () => {
  const { result } = renderHook(() => useCounter(5))

  expect(result.current.count).toBe(5)

  act(() => result.current.increment())
  expect(result.current.count).toBe(6)

  act(() => result.current.decrement())
  expect(result.current.count).toBe(5)
})

3. Checking state and updates with result.current

The central access point in every renderHook test is result.current. After every state update, this value must be re-read, because while result.current gets updated automatically, an already destructured variable keeps holding the old value. A common beginner mistake is destructuring const { count } = result.current once at the start of the test and then continuing to work with the stale copy, instead of accessing result.current again each time.

For more complex custom hooks that manage several interrelated state values, for example a form hook with values, errors and isSubmitting, it is worth checking only the relevant slice of result.current in each test, instead of bundling the entire return value into a single, unwieldy assertion.

// useToggle.test.ts — checking result.current after each state change
import { renderHook, act } from '@testing-library/react'
import { useToggle } from './useToggle'

test('toggles boolean state on each call', () => {
  const { result } = renderHook(() => useToggle(false))

  expect(result.current.value).toBe(false)

  act(() => result.current.toggle())
  // Must re-read result.current — the old destructured value is stale
  expect(result.current.value).toBe(true)

  act(() => result.current.toggle())
  expect(result.current.value).toBe(false)
})

4. act() and when it is really needed

act() ensures that all React state updates inside the callback are fully processed before the next assertion runs. Without act() around a state update call, React can print a warning in the test log, because the update happens outside the controlled render cycle. The rule: every interaction with the custom hook that internally triggers setState belongs inside act().

Newer versions of renderHook and Testing Library already wrap many cases automatically in act(), in particular the initial render and rerender() calls. Manual act() remains necessary, though, when a function returned by the hook gets called outside these automatic wrappers, for example a direct call to result.current.increment() inside a test assertion.

5. Testing async hooks with waitFor

Many custom hooks encapsulate asynchronous logic, for example loading data in a useEffect or a debounced search. For these cases, act() alone is not enough, because the update only arrives after a promise chain completes. Testing Library provides waitFor for this, which repeatedly checks until a condition is met, without hard-coding fixed timeouts in the test.

A common pattern: a custom hook like useFetch first sets isLoading: true, then performs the request and updates state asynchronously. The test first checks the initial loading state synchronously, then waits with waitFor for the final state, instead of assuming the update is immediately available.

// useFetch.test.ts — testing an async custom hook
import { renderHook, waitFor } from '@testing-library/react'
import { useFetch } from './useFetch'

test('loads data asynchronously and updates state', async () => {
  const { result } = renderHook(() => useFetch('/api/users/1'))

  // Synchronous initial state, no waiting needed
  expect(result.current.isLoading).toBe(true)
  expect(result.current.data).toBeNull()

  // Wait until the async effect resolves and updates state
  await waitFor(() => {
    expect(result.current.isLoading).toBe(false)
  })

  expect(result.current.data).toEqual({ id: '1', name: 'Ada Lovelace' })
  expect(result.current.error).toBeNull()
})

6. Wrapper providers for hooks with a context dependency

Many custom hooks access a provider via useContext, for example for theming, authentication or feature flags. renderHook accepts the wrapper option for this, a component that wraps the hook during rendering and provides the required context. Without this wrapper, the hook would work with the context's default value or throw an error if the context is mandatory.

This pattern makes it possible to test the same custom hook with different context values, for example a logged-in and a logged-out state, without changing the actual hook implementation. The wrapper gets reassembled per test or per describe block, depending on which state needs to be checked.

// useCurrentUser.test.ts — providing context via the wrapper option
import { renderHook } from '@testing-library/react'
import { AuthContext } from '../AuthContext'
import { useCurrentUser } from './useCurrentUser'

function createWrapper(user: { id: string; name: string } | null) {
  return function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <AuthContext.Provider value={{ user, isAuthenticated: user !== null }}>
        {children}
      </AuthContext.Provider>
    )
  }
}

test('returns the authenticated user from context', () => {
  const { result } = renderHook(() => useCurrentUser(), {
    wrapper: createWrapper({ id: '1', name: 'Ada Lovelace' }),
  })

  expect(result.current.isAuthenticated).toBe(true)
  expect(result.current.user?.name).toBe('Ada Lovelace')
})

test('returns null when no user is authenticated', () => {
  const { result } = renderHook(() => useCurrentUser(), {
    wrapper: createWrapper(null),
  })

  expect(result.current.isAuthenticated).toBe(false)
})

7. rerender() for prop changes and cleanup effects

Some custom hooks react to changes in their arguments, for example a useDebounce(value, delay) that starts a new timer every time value changes. rerender(newArgs) simulates exactly this behavior by re-executing the hook callback with the new arguments, without needing to set up the entire test again.

Just as important is testing cleanup effects via unmount(). A custom hook that starts an interval or registers an event listener inside a useEffect should remove it again on unmount. The test calls unmount() and then checks whether the corresponding cleanup function, for example clearInterval or removeEventListener, was actually called.

// useInterval.test.ts — rerender for changed deps, unmount for cleanup
import { renderHook } from '@testing-library/react'
import { useInterval } from './useInterval'

test('restarts the interval when delay changes', () => {
  const callback = vi.fn()
  const { rerender } = renderHook(
    ({ delay }) => useInterval(callback, delay),
    { initialProps: { delay: 1000 } }
  )

  rerender({ delay: 500 })
  // Assertions on timer behavior would follow with vi.useFakeTimers()
})

test('clears the interval on unmount', () => {
  const clearIntervalSpy = vi.spyOn(global, 'clearInterval')
  const { unmount } = renderHook(() => useInterval(() => {}, 1000))

  unmount()
  expect(clearIntervalSpy).toHaveBeenCalledTimes(1)
})

8. Common pitfalls in hook tests

The most common mistake in tests with renderHook is forgetting act() around synchronous state updates, followed by using stale, already destructured values instead of accessing result.current again. Another widespread mistake concerns custom hooks that rely on refs instead of state to memoize expensive calculations: a test that only checks result.current after a render might not see that the ref updated correctly, because ref changes do not trigger a re-render.

A third pitfall concerns timer-based custom hooks. Without vi.useFakeTimers(), a test has to wait for a real debounce or a real interval, which unnecessarily slows down test runs and causes flakiness in CI environments. Fake timers combined with act(() => vi.advanceTimersByTime(500)) solve this by fast-forwarding time in a controlled way inside the test, instead of letting it pass for real.

9. renderHook compared to testing via the host component

Both approaches have their merits but cover different aspects. The table below shows when each approach is preferable.

In practice, both levels complement each other. An isolated test with renderHook fully covers the custom hook's logic, while an additional, lean test via the host component ensures the integration with the UI works, without that second test needing to retest every single branch of the hook again.

10. Summary

Testing custom hooks in isolation separates the responsibility of hook logic from the responsibility of UI rendering and makes the cause of failures immediately apparent. renderHook provides access to the current return value via result.current, act() synchronizes state updates, waitFor covers asynchronous logic, and the wrapper option enables tests for hooks with a context dependency.

The biggest gain lies in reusability: a cleanly tested custom hook does not need to be retested indirectly in every component that uses it. This significantly reduces test duplication, speeds up the test suite, and makes the cause of a failure immediately visible, instead of having to guess between hook logic and component rendering.

11. FAQ: Testing Custom Hooks in Isolation