@testing-library/react-hooks
    TypeScript icon, indicating that this package has built-in type declarations

    7.0.2 • Public • Published

    react-hooks-testing-library

    ram

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


    Read The Docs

    Build Status codecov version downloads MIT License

    All Contributors PRs Welcome Code of Conduct Netlify Status Discord

    Watch on GitHub Star on GitHub Tweet

    Table of Contents

    The problem

    You're writing an awesome custom hook and you want to test it, but as soon as you call it you see the following error:

    Invariant Violation: Hooks can only be called inside the body of a function component.

    You don't really want to write a component solely for testing this hook and have to work out how you were going to trigger all the various ways the hook can be updated, especially given the complexities of how you've wired the whole thing together.

    The solution

    The react-hooks-testing-library allows you to create a simple test harness for React hooks that handles running them within the body of a function component, as well as providing various useful utility functions for updating the inputs and retrieving the outputs of your amazing custom hook. This library aims to provide a testing experience as close as possible to natively using your hook from within a real component.

    Using this library, you do not have to concern yourself with how to construct, render or interact with the react component in order to test your hook. You can just use the hook directly and assert the results.

    When to use this library

    1. You're writing a library with one or more custom hooks that are not directly tied to a component
    2. You have a complex hook that is difficult to test through component interactions

    When not to use this library

    1. Your hook is defined alongside a component and is only used there
    2. Your hook is easy to test by just testing the components using it

    Example

    useCounter.js

    import { useState, useCallback } from 'react'
    
    function useCounter() {
      const [count, setCount] = useState(0)
    
      const increment = useCallback(() => setCount((x) => x + 1), [])
    
      return { count, increment }
    }
    
    export default useCounter

    useCounter.test.js

    import { renderHook, act } from '@testing-library/react-hooks'
    import useCounter from './useCounter'
    
    test('should increment counter', () => {
      const { result } = renderHook(() => useCounter())
    
      act(() => {
        result.current.increment()
      })
    
      expect(result.current.count).toBe(1)
    })

    More advanced usage can be found in the documentation.

    Installation

    npm install --save-dev @testing-library/react-hooks

    Peer Dependencies

    react-hooks-testing-library does not come bundled with a version of react to allow you to install the specific version you want to test against. It also does not come installed with a specific renderer, we currently support react-test-renderer and react-dom. You only need to install one of them, however, if you do have both installed, we will use react-test-renderer as the default. For more information see the installation docs. Generally, the installed versions for react and the selected renderer should have matching versions:

    npm install react@^16.9.0
    npm install --save-dev react-test-renderer@^16.9.0

    NOTE: The minimum supported version of react, react-test-renderer and react-dom is ^16.9.0.

    API

    See the API reference.

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Michael Peyper

    💻 📖 🤔 🚇 🚧 💬 ⚠️

    otofu-square

    💻

    Patrick P. Henley

    🤔 👀

    Matheus Marques

    💻

    Dhruv Patel

    🐛 👀

    Nathaniel Tucker

    🐛 👀

    Sergei Grishchenko

    💻 📖 🤔

    Josep M Sobrepere

    📖

    Marcel Tinner

    📖

    Daniel K.

    🐛 💻

    Vince Malone

    💻

    Sebastian Weber

    📝

    Christian Gill

    📖

    JavaScript Joe


    Sarah Dayan

    📦

    Roman Gusev

    📖

    Adam Seckel

    💻

    keiya sasaki

    ⚠️

    Hu Chen

    💻 📖 💡

    Josh

    📖 💬 💻 🤔 🚧 ⚠️

    Na'aman Hirschfeld

    💻

    Braydon Hall

    💻

    Jacob M-G Evans

    💻 ⚠️

    Tiger Abrodi

    💻 ⚠️

    Amr A.Mohammed

    💻 ⚠️

    Juhana Jauhiainen

    💻

    Jens Meindertsma

    💻 ⚠️

    Marco Moretti

    🚇

    Martin V.

    📖

    Erozak

    📖

    Nick McCurdy

    🚧

    Arya

    📖

    numb86

    📖

    Alex Young

    🚧

    Ben Lambert

    📖

    David Cho-Lerat

    📖

    Evan Harmon

    📖

    Jason Brown

    📖

    KahWee Teng

    📖

    Leonid Shagabutdinov

    📖

    Levi Butcher

    📖

    Michele Settepani

    📖

    Sam

    📖

    Tanay Pratap

    📖

    Tom Rees-Herdman

    📖

    iqbal125

    📖

    cliffzhaobupt

    🚧

    Jon Koops

    💻

    Jonathan Peyper

    👀 💻

    Sean Baines

    📖

    Mikhail Vasin

    📖

    Aleksandar Grbic

    📖

    Jonathan Holmes

    💻

    Michaël De Boey

    🚧

    Anton Zinovyev

    🐛 💻

    marianna-exelate

    🚇

    Matan Borenkraout

    🚧

    andyrooger

    💻

    Bryan Wain

    🐛 👀

    Robert Snow

    ⚠️

    Chris Chen

    ⚠️

    Masious

    📖

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Issues

    Looking to contribute? Look for the Good First Issue label.

    🐛 Bugs

    Please file an issue for bugs, missing documentation, or unexpected behavior.

    See Bugs

    💡 Feature Requests

    Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

    See Feature Requests

    Questions

    For questions related to using the library, you can raise issue here, or visit a support community:

    LICENSE

    MIT

    Install

    npm i @testing-library/react-hooks

    DownloadsWeekly Downloads

    1,240,930

    Version

    7.0.2

    License

    MIT

    Unpacked Size

    137 kB

    Total Files

    98

    Last publish

    Collaborators

    • testing-library-bot
    • kentcdodds
    • bcarroll22
    • benmonro
    • wendell_adriel
    • timdeschryver
    • patrickhulce
    • dfcook
    • gpx
    • mpeyper
    • antoaravinth
    • mihar-22
    • pago
    • cmckinstry
    • thymikee
    • brrianalexis