Developers of the most popular React Hooks libraries rely on tests to enforce the overall quality of their libraries' code. Tests cover a wide variety of different use cases, give developers confidence that everything works as intended and serve as a form of documentation. Anytime a test fails, developers know which set of arguments to use to replicate the bug encountered and squash it lands in the distribution package. When writing a custom React Hook for a library, the Hook should be tested regularly and against the fringest of edge cases to appeal to a greater number of projects.

Setting up a testing environment that executes tests fast and reliably requires the proper tools:

This testing environment allows you to write tests that closely resemble your user's actions. For example, 

 comes with methods for rendering a React component (

 by default) and finding an element within the rendered content of this container via the element's label (

import {render, screen} from "@testing-library/react";

test('should show contact form', () => {
  render(<ContactForm />);
  
  // Query by the element's `aria-label` attribute value, wrapper label, etc. 
  const input = screen.getByLabelText('E-Mail Address');

  // ...
});

With just these two methods, our test mimics, at a high-level, the browser rendering a contact form to the screen and the user searching for an e-mail address input field.

In the case of React Hooks, you may not want to create dummy components for the sole purpose of testing your Hooks. A unit test for a React Hook should only test the Hook's functionality (independent of any component calling it). We should reserve the testing of Hooks called within a component for integration tests. Fortunately, the 

 library gives us testing utilities for testing Hooks in isolation without having to render any dummy components.

Below, I'm going to show you how to test a custom React Hook built for a React Hooks library with the 

To get started, clone this React Hooks library template from GitHub:

$ git clone -b use-map https://github.com/newline-sandbox/react-hooks-library.git

This template has ESLint, TypeScript and Jest already configured and comes with a custom React Hook, 

, which we will write tests for. Additionally, the 

 library has already been installed as a dev. dependency.

 object and mimics its API. If you would like to learn how to implement this Hook from scratch, then check out the blog post 

Within this file, import two methods from the 

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

 block with the text "useMap" to group all tests related to the 

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

describe("useMap", () => {
  // `describe` and `it` statements...
});

 state variable, which represents the Hook's current 

 Hook provides several action methods for updating this state variable:

 blocks and tests will be written within the 

 action method that covers two cases involving this action method:

describe("set", () => {
  it("should update an existing key-value pair", () => {
    // ...
  });
  it("should add a new key-value pair", () => {
    // ...
  });
});

For the "should update an existing key-value pair," we should render the 

const { result } = renderHook(() =>
  useMap<number, string>([[1, "default"]])
);

Here, we call the Hook with an array of one key-value pair. We pass this to a new 

 field. This field is a React ref. By reading the ref's 

 field, you can access the Hook's API (an array that contains the 

 state variable and the action methods). For now, let's omit the 

 state variable. I will explain why later on.

Let's double-check that our initial state was set correctly to a 

expect(result.current[0].get(1)).toBe("default");

Save the changes. In the terminal, run the 

 npm script to verify that the initial state is set correctly:

 method to flush any changes to the state into the simulated DOM before running any subsequent assertions.

Check that the key-value pair has been updated. The 

 key should have a corresponding value of 

expect(result.current[0].get(1)).toBe("changed");

 npm script to verify that the state has correctly changed:

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

describe("useMap", () => {
  describe("set", () => {
    it("should update an existing key-value pair", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "default"]])
      );
      const [, { set }] = result.current;
      expect(result.current[0].get(1)).toBe("default");
      act(() => set(1, "changed"));
      expect(result.current[0].get(1)).toBe("changed");
    });
  });
});

With these few steps, you can write tests for the remaining action methods:

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

describe("useMap", () => {
  describe("set", () => {
    it("should update an existing key-value pair", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "default"]])
      );
      const [, { set }] = result.current;
      expect(result.current[0].get(1)).toBe("default");
      act(() => set(1, "changed"));
      expect(result.current[0].get(1)).toBe("changed");
    });
    it("should add a new key-value pair", () => {
      const { result } = renderHook(() => useMap<number, string>());
      const [, { set }] = result.current;
      expect(result.current[0].get(1)).toBeUndefined();
      act(() => set(1, "added"));
      expect(result.current[0].get(1)).toBe("added");
    });
  });

  describe("delete", () => {
    it("should delete an existing key-value pair", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "existing"]])
      );
      const [, { delete: deleteByKey }] = result.current;
      expect(result.current[0].get(1)).toBe("existing");
      act(() => deleteByKey(1));
      expect(result.current[0].get(1)).toBeUndefined();
    });
  });

  describe("initialize", () => {
    // The first row of the table defines the variable names used in the tests. `|` separates columns.
    // https://jestjs.io/docs/api#2-testeachtablename-fn-timeout
    // Two tests:
    // * For the "map" test, we initialize the map with the map `Map([[1, "initialized"]])`.
    // * For the "tuple" test, we initialize the map with the tuple `[1, "initialized"]`.
    it.each`
      message    | input
      ${"map"}   | ${new Map([[1, "initialized"]])}
      ${"tuple"} | ${[[1, "initialized"]]}
    `("should initialize with a $message", ({ input }) => {
      const { result } = renderHook(() => useMap<number, string>());
      const [, { initialize }] = result.current;
      expect(result.current[0].get(1)).toBeUndefined();
      act(() => initialize(input));
      expect(result.current[0].get(1)).toBe("initialized");
    });
  });

  describe("clear", () => {
    it("should clear all key-value pairs", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "initialized"]])
      );
      const [, { clear }] = result.current;
      expect(result.current[0].get(1)).toBe("initialized");
      act(() => clear());
      expect(result.current[0].get(1)).toBeUndefined();
    });
  });
});

 state variable and only accessed it from 

? This is because all action methods are immutable. Therefore, anytime we call any one of these action methods, the 

 state variable destructured from the initial 

 object that set it to internally in the Hook. Essentially, after the action method call, 

 object than the one referenced by the destructured 

 block labeled "hook optimizations." Inside of this 

 block, write a test to confirm this behavior:

describe("hook optimizations", () => {
  it("should change value reference equality after change", () => {
    const { result } = renderHook(() => useMap<number, number>());
    const [originalValueReference, { set }] = result.current;
    expect(result.current[0]).toBe(originalValueReference);
    act(() => set(1, 1));
    expect(originalValueReference).not.toBe(result.current[0]);
    expect(originalValueReference.get(1)).toBeUndefined();
    expect(result.current[0].get(1)).toBe(1);
  });
});

Finally, let's write a test to make sure our 

 optimizations maintain reference equality after state changes. The reference to the action methods should never change.

it("should keep actions reference equality after value change", () => {
  const { result } = renderHook(() => useMap<number, number>());
  const [, originalActionsReference] = result.current;
  expect(result.current[1]).toBe(originalActionsReference);
  act(() => originalActionsReference.set(1, 1));
  expect(originalActionsReference).toBe(result.current[1]);
});

Run the tests one final time and watch them all pass!

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

describe("useMap", () => {
  describe("set", () => {
    it("should update an existing key-value pair", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "default"]])
      );
      const [, { set }] = result.current;
      expect(result.current[0].get(1)).toBe("default");
      act(() => set(1, "changed"));
      expect(result.current[0].get(1)).toBe("changed");
    });
    it("should add a new key-value pair", () => {
      const { result } = renderHook(() => useMap<number, string>());
      const [, { set }] = result.current;
      expect(result.current[0].get(1)).toBeUndefined();
      act(() => set(1, "added"));
      expect(result.current[0].get(1)).toBe("added");
    });
  });

  describe("delete", () => {
    it("should delete an existing key-value pair", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "existing"]])
      );
      const [, { delete: deleteByKey }] = result.current;
      expect(result.current[0].get(1)).toBe("existing");
      act(() => deleteByKey(1));
      expect(result.current[0].get(1)).toBeUndefined();
    });
  });

  describe("initialize", () => {
    // The first row of the table defines the variable names used in the tests. `|` separates columns.
    // https://jestjs.io/docs/api#2-testeachtablename-fn-timeout
    // Two tests:
    // * For the "map" test, we initialize the map with the map `Map([[1, "initialized"]])`.
    // * For the "tuple" test, we initialize the map with the tuple `[1, "initialized"]`.
    it.each`
      message    | input
      ${"map"}   | ${new Map([[1, "initialized"]])}
      ${"tuple"} | ${[[1, "initialized"]]}
    `("should initialize with a $message", ({ input }) => {
      const { result } = renderHook(() => useMap<number, string>());
      const [, { initialize }] = result.current;
      expect(result.current[0].get(1)).toBeUndefined();
      act(() => initialize(input));
      expect(result.current[0].get(1)).toBe("initialized");
    });
  });

  describe("clear", () => {
    it("should clear all key-value pairs", () => {
      const { result } = renderHook(() =>
        useMap<number, string>([[1, "initialized"]])
      );
      const [, { clear }] = result.current;
      expect(result.current[0].get(1)).toBe("initialized");
      act(() => clear());
      expect(result.current[0].get(1)).toBeUndefined();
    });
  });

  describe("hook optimizations", () => {
    it("should change value reference equality after change", () => {
      const { result } = renderHook(() => useMap<number, number>());
      const [originalValueReference, { set }] = result.current;
      expect(result.current[0]).toBe(originalValueReference);
      act(() => set(1, 1));
      expect(originalValueReference).not.toBe(result.current[0]);
      expect(originalValueReference.get(1)).toBeUndefined();
      expect(result.current[0].get(1)).toBe(1);
    });
  });

  it("should keep actions reference equality after value change", () => {
    const { result } = renderHook(() => useMap<number, number>());
    const [, originalActionsReference] = result.current;
    expect(result.current[1]).toBe(originalActionsReference);
    act(() => originalActionsReference.set(1, 1));
    expect(originalActionsReference).toBe(result.current[1]);
  });
});

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Testing a Custom React Hook (useMap)

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript