Testing hooks and context: renderHook, fake timers, stale snapshots

What renderHook actually does

Hooks cannot run outside a component — the Rules of React are physics, not style. renderHook (shipped in @testing-library/react) makes the smallest legal physics lab: it mounts a throwaway host component, calls your hook inside it with initialProps, and copies the hook’s return value onto result.current after every committed render. Nothing else is special — which is exactly why its API is shaped the way it is:

const { result, rerender, unmount } = renderHook(
  ({ userId }) => usePermissions(userId),
  {
    initialProps: { userId: "u1" },
    wrapper: ({ children }) => (
      <PermissionsProvider value={stubPermissions}>{children}</PermissionsProvider>
    ),
  },
);

rerender({ userId: "u2" });           // re-renders the host with new props
expect(result.current.canEdit).toBe(false);
unmount();                            // runs effect cleanups — test them too

wrapper is the provider injection point, and it carries a design decision: pass a stub provider value — a plain object implementing the context’s contract — rather than vi.mock-ing the provider module. A stub value exercises the real useContext wiring and survives provider refactors; a module mock couples the test to file paths and export shapes. For context like a query client, the rule has a sharper edge: create a fresh client per test inside the wrapper, or cached data leaks between tests and manufactures order dependence.

When should a hook get its own test at all? Test the hook directly when it is the public contract — a shared usePagination consumed by twelve teams deserves contract tests independent of any one consumer. When the hook exists to serve one component, test the component: a hook test can stay green while the component integration is broken (wrong prop threading, render timing), and a senior suite spends its budget where the user-visible contract lives.

Reading result.current: identity, not timing

result.current is a property the harness reassigns after every commit. When you see an assertion that destructures result at the top of a test and reads from it later, flag it immediately — it is the most common silent bug in hook test suites. Three consequences, each a code-review checkpoint. First — never destructure: const { current } = result (or const value = result.current saved for later) freezes one render’s output; every assertion after the next state update reads history. The correct idiom is boringly repetitive: result.current.x at every read site, because each read must observe the latest commit. Second — updates need act: calling result.current.save() outside act fires the state update without flushing it deterministically (and warns); wrap state-changing calls, await async ones. Third — after unmount(), result.current keeps the last committed value, which is useful for asserting final state but means “no error on read” does not prove the hook is still alive; what unmount actually verifies is cleanup — intervals cleared, subscriptions closed, pending debounce flushed or cancelled, whichever your contract promises.

Fake timers, debounce, and the user-event deadlock

A debounced or interval hook tested against the real clock costs real seconds per test and still flakes under CI load. Fake timers make time a controlled input: vi.useFakeTimers() swaps the global timer functions for a virtual clock, and vi.advanceTimersByTime(800) fires exactly the callbacks due in that window — deterministic, instant, load-independent. The discipline around them:

it("saves once after 800 ms of silence", async () => {
  vi.useFakeTimers();
  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
  render(<Editor />);

  await user.type(screen.getByRole("textbox"), "draft");

  act(() => { vi.advanceTimersByTime(799); });
  expect(saveSpy).not.toHaveBeenCalled();      // boundary: nothing at 799

  act(() => { vi.advanceTimersByTime(1); });
  expect(saveSpy).toHaveBeenCalledTimes(1);    // fires exactly at 800

  vi.useRealTimers();                          // always restore — afterEach is safer
});

The advanceTimers option is the deadlock breaker from the Hook: user-event paces its event sequences through setTimeout, so under a frozen fake clock every await user.type(...) waits forever unless user-event is told how to advance the clock itself. Wire advanceTimers: vi.advanceTimersByTime at setup time — every team that adopts fake timers without it loses a day to a hung test. The boundary assertion pattern (799 then 1) is what makes a debounce test worth having: it pins the contract — fires once, fires at the deadline, does not fire early — rather than “called eventually”. Two honest caveats keep this technique from biting back. Fake timers fake timers, not microtasks: resolved-promise continuations still run on the real microtask queue, so advanceTimersByTime inside act plus an await afterward is the shape that lets both queues drain. And a leaked fake clock is a suite-wide contaminant — restore in afterEach(() => vi.useRealTimers()), because the next test’s waitFor polls on the very setTimeout you froze, and its 1-second budget never starts ticking.