API Reference (original) (raw)

react-hooks-testing-library exports the following methods:

renderHook

function renderHook(callback: (props?: any) => any, options?: RenderHookOptions): RenderHookResult

Renders a test component that will call the provided callback, including any hooks it calls, every time it renders.

The renderHook function accepts the following arguments:

callback

The function that is called each render of the test component. This function should call one or more hooks for testing.

The props passed into the callback will be the initialProps provided in the options torenderHook, unless new props are provided by a subsequent rerender call.

options (Optional)

An options object to modify the execution of the callback function. See therenderHook Options section for more details.

renderHook Options

The renderHook function accepts the following options as the second parameter:

initialProps

The initial values to pass as props to the callback function of renderHook.

wrapper

A React component to wrap the test component in when rendering. This is usually used to add context providers from React.createContext for the hook to access with useContext. initialProps and props subsequently set by rerender will be provided to the wrapper.

renderHook Result

The renderHook function returns an object that has the following properties:

result

{

all: Array

current: any,

error: Error

}

The current value of the result will reflect the latest of whatever is returned from thecallback passed to renderHook. Any thrown values from the latest call will be reflected in theerror value of the result. The all value is an array containing all the returns (including the most recent) from the callback. These could be result or an error depending on what the callback returned at the time.

rerender

function rerender(newProps?: any): void

A function to rerender the test component, causing any hooks to be recalculated. If newProps are passed, they will replace the callback function's initialProps for subsequent rerenders.

unmount

A function to unmount the test component. This is commonly used to trigger cleanup effects foruseEffect hooks.

hydrate

This is only used when using the server module. See SSR for more information on server-side rendering your hooks.

A function to hydrate a server rendered component into the DOM. This is required before you can interact with the hook, whether that is an act or rerender call. Effects created usinguseEffect or useLayoutEffect are also not run on server rendered hooks until hydrate is called.

...asyncUtils

Utilities to assist with testing asynchronous behaviour. See theAsync Utils section for more details.

act

This is the same act function function that is exported from your chosen renderer.

cleanup

function cleanup(): Promise

Unmounts any rendered hooks rendered with renderHook, ensuring all effects have been flushed. Any callbacks added with addCleanup will also be called whencleanup is run.

Please note that this is done automatically if the testing framework you're using supports theafterEach global (like Jest, mocha and Jasmine). If not, you will need to do manual cleanups after each test.

The cleanup function should be called after each test to ensure that previously rendered hooks will not have any unintended side-effects on the following tests.

Skipping Auto-Cleanup

Importing @testing-library/react-hooks/dont-cleanup-after-each.js in test setup files will disable the auto-cleanup feature.

For example, in Jest this can be added to yourJest config:

module.exports = {

setupFilesAfterEnv: [

'@testing-library/react-hooks/dont-cleanup-after-each.js'

]

}

Alternatively, you can change your test to import from @testing-library/react-hooks/pure (or any of the other non-pure imports) instead of the regular imports.

If neither of these approaches are suitable, setting the RHTL_SKIP_AUTO_CLEANUP environment variable to true before importing @testing-library/react-hooks will also disable this feature.

addCleanup

function addCleanup(callback: () => void | Promise): (): void

Add a callback to be called during cleanup, returning a function to remove the cleanup if is no longer required. Cleanups are called in reverse order to being added. This is usually only relevant when wanting a cleanup to run after the component has been unmounted.

If the provided callback is an async function or returns a promise, cleanup will wait for it to be resolved before moving onto the next cleanup callback.

Please note that any cleanups added using addCleanup are removed after cleanup is called. For cleanups that need to run with every test, it is advised to add them in a beforeEach block (or equivalent for your test runner).

removeCleanup

function removeCleanup(callback: () => void | Promise): void

Removes a cleanup callback previously added with addCleanup. Once removed, the provided callback will no longer execute as part of runningcleanup.

Async Utilities

waitForNextUpdate

function waitForNextUpdate(options?: { timeout?: number | false }): Promise

Returns a Promise that resolves the next time the hook renders, commonly when state is updated as the result of an asynchronous update.

timeout

Default: 1000

The maximum amount of time in milliseconds (ms) to wait.

waitFor

function waitFor(

callback: () => boolean | void,

options?: {

interval?: number | false

timeout?: number | false

}

): Promise

Returns a Promise that resolves if the provided callback executes without exception and returns a truthy or undefined value. It is safe to use the result of renderHookin the callback to perform assertion or to test values.

interval

Default: 50

The amount of time in milliseconds (ms) to wait between checks of the callback if no renders occur. Interval checking is disabled if interval is not provided as a falsy.

timeout

Default: 1000

The maximum amount of time in milliseconds (ms) to wait.

waitForValueToChange

function waitForValueToChange(

selector: () => any,

options?: {

interval?: number | false

timeout?: number | false

}

): Promise

Returns a Promise that resolves if the value returned from the provided selector changes. It is expected that the result of renderHook will be used to select the value for comparison.

interval

Default: 50

The amount of time in milliseconds (ms) to wait between checks of the callback if no renders occur. Interval checking is disabled if interval is not provided as a falsy.

timeout

Default: 1000

The maximum amount of time in milliseconds (ms) to wait.

console.error

In order to catch errors that are produced in all parts of the hook's lifecycle, the test harness used to wrap the hook call includes anError Boundary which causes asignificant amount of output noisein tests.

To keep test output clean, we patch console.error when importing from@testing-library/react-hooks (or any of the other non-pure imports) to filter out the unnecessary logging and restore the original version during cleanup. This side-effect can affect tests that also patch console.error (e.g. to assert a specific error message get logged) by replacing their custom implementation as well.

Please note that this is done automatically if the testing framework you're using supports thebeforeEach and afterEach global (like Jest, mocha and Jasmine). If not, you will need to domanual suppression around the test run.

Disabling console.error filtering

Importing @testing-library/react-hooks/disable-error-filtering.js in test setup files disable the error filtering feature and not patch console.error in any way.

For example, in Jest this can be added to yourJest config:

module.exports = {

setupFilesAfterEnv: [

'@testing-library/react-hooks/disable-error-filtering.js'

]

}

Alternatively, you can change your test to import from @testing-library/react-hooks (or any of theother non-pure imports) instead of the regular imports.

If neither of these approaches are suitable, setting the RHTL_DISABLE_ERROR_FILTERING environment variable to true before importing @testing-library/react-hooks will also disable this feature.

Please note that this may result in a significant amount of additional logging in your test output.

Manually suppress output

If you are using a pure import, you are running your tests in an environment that does not support beforeEach and afterEach, or if the automatic suppression is not available to you for some other reason, then you can use the suppressErrorOutput export to manually start and top suppress the output:

import { renderHook, suppressErrorOutput } from '@testing-library/react-hooks/pure'

test('should handle thrown error', () => {

const restoreConsole = suppressErrorOutput()

try {

const { result } = renderHook(() => useCounter())

expect(result.error).toBeDefined()

} finally {

restoreConsole()

}

})