or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

act-utilities.mdasync-testing.mdcleanup-management.mderror-handling.mdhook-rendering.mdindex.mdserver-side-rendering.md
tile.json

tessl/npm-testing-library--react-hooks

Simple and complete React hooks testing utilities that encourage good testing practices.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@testing-library/react-hooks@8.0.x

To install, run

npx @tessl/cli install tessl/npm-testing-library--react-hooks@8.0.0

index.mddocs/

React Hooks Testing Library

React Hooks Testing Library provides simple and complete testing utilities for React hooks, encouraging good testing practices. It allows you to test custom hooks in isolation without creating wrapper components, handling the complexities of running hooks within function components while providing utilities for updating inputs and retrieving outputs.

Package Information

  • Package Name: @testing-library/react-hooks
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @testing-library/react-hooks

Core Imports

import { renderHook, act } from "@testing-library/react-hooks";

For specific renderer environments:

// DOM environment (default auto-detected)
import { renderHook, act } from "@testing-library/react-hooks/dom";

// React Native environment
import { renderHook, act } from "@testing-library/react-hooks/native";

// Server-side rendering environment
import { renderHook, act } from "@testing-library/react-hooks/server";

// Pure environment (no auto-setup)
import { renderHook, act } from "@testing-library/react-hooks/pure";

CommonJS:

const { renderHook, act } = require("@testing-library/react-hooks");

Basic Usage

import { renderHook, act } from "@testing-library/react-hooks";
import { useState } from "react";

// Test a simple custom hook
function useCounter(initialCount = 0) {
  const [count, setCount] = useState(initialCount);
  
  const increment = () => setCount(prev => prev + 1);
  const decrement = () => setCount(prev => prev - 1);
  
  return { count, increment, decrement };
}

test("useCounter hook", () => {
  const { result } = renderHook(() => useCounter(5));
  
  // Check initial value
  expect(result.current.count).toBe(5);
  
  // Test increment
  act(() => {
    result.current.increment();
  });
  
  expect(result.current.count).toBe(6);
  
  // Test decrement
  act(() => {
    result.current.decrement();
  });
  
  expect(result.current.count).toBe(5);
});

Architecture

React Hooks Testing Library is built around several key components:

  • renderHook Function: Core testing utility that renders hooks in a test environment
  • act Utility: Wraps state updates to ensure proper batching and timing
  • Renderer Abstraction: Supports multiple React renderers (DOM, Native, Server)
  • Async Utilities: Built-in utilities for waiting on asynchronous hook updates
  • Cleanup System: Automatic and manual cleanup of rendered hooks
  • Error Handling: Comprehensive error boundary and suppression utilities

Capabilities

Hook Rendering

Core functionality for rendering and testing React hooks in isolation. The renderHook function creates a test harness that runs your hook within a proper React component context.

function renderHook<TProps, TResult>(
  callback: (props: TProps) => TResult,
  options?: RenderHookOptions<TProps>
): RenderHookResult<TProps, TResult>;

interface RenderHookOptions<TProps> {
  initialProps?: TProps;
  wrapper?: React.ComponentType<TProps>;
}

Hook Rendering

Act Utilities

State update wrapping utilities that ensure proper timing and batching of React updates during testing. Essential for testing hooks that perform state updates or side effects.

function act(callback: () => void | undefined): void;
function act(callback: () => Promise<void | undefined>): Promise<undefined>;

Act Utilities

Async Testing

Utilities for testing asynchronous hook behavior, including waiting for updates, value changes, and condition fulfillment.

interface AsyncUtils {
  waitFor(callback: () => boolean | void, options?: WaitForOptions): Promise<void>;
  waitForValueToChange(selector: () => unknown, options?: WaitForValueToChangeOptions): Promise<void>;
  waitForNextUpdate(options?: WaitForNextUpdateOptions): Promise<void>;
}

interface WaitForOptions {
  interval?: number | false;
  timeout?: number | false;
}

Async Testing

Cleanup Management

Cleanup utilities for managing test teardown, both automatic and manual cleanup of rendered hooks and associated resources.

function cleanup(): Promise<void>;
function addCleanup(callback: CleanupCallback): () => void;
function removeCleanup(callback: CleanupCallback): void;

type CleanupCallback = () => Promise<void> | void;

Cleanup Management

Error Handling

Error suppression and handling utilities for testing error scenarios and managing console output during tests.

function suppressErrorOutput(): () => void;

Error Handling

Server-Side Rendering

Server-specific rendering capabilities for testing hooks in SSR environments with hydration support. Only available when using the server renderer.

interface ServerRenderHookResult<TProps, TValue> extends RenderHookResult<TProps, TValue> {
  hydrate(): void;
}

When using @testing-library/react-hooks/server, the renderHook function returns a result that includes a hydrate() method for testing server-side rendering scenarios.

Server-Side Rendering

Types

interface RenderHookResult<TProps, TValue> {
  result: {
    readonly current: TValue;
    readonly all: Array<TValue | Error>;
    readonly error?: Error;
  };
  rerender: (newProps?: TProps) => void;
  unmount: () => void;
  waitFor: (callback: () => boolean | void, options?: WaitForOptions) => Promise<void>;
  waitForValueToChange: (selector: () => unknown, options?: WaitForValueToChangeOptions) => Promise<void>;
  waitForNextUpdate: (options?: WaitForNextUpdateOptions) => Promise<void>;
}

interface WrapperComponent<TProps> extends React.ComponentType<TProps> {}

type Act = {
  (callback: () => Promise<void | undefined>): Promise<undefined>;
  (callback: () => void | undefined): void;
}

interface WaitForOptions {
  interval?: number | false;
  timeout?: number | false;
}

interface WaitForValueToChangeOptions {
  interval?: number | false;
  timeout?: number | false;
}

interface WaitForNextUpdateOptions {
  timeout?: number | false;
}

class TimeoutError extends Error {
  constructor(util: Function, timeout: number);
}