Async Methods

Several utilities are provided for dealing with asynchronous code. These can be useful to wait for an element to appear or disappear in response to an event, user action, timeout, or Promise. (See the guide to testing disappearance.)

The async methods return Promises, so be sure to use await or .then when calling them.

findBy Queries

findBy methods are a combination of getBy queries and waitFor. They accept the waitFor options as the last argument (e.g. await screen.findByText('text', queryOptions, waitForOptions)).

findBy queries work when you expect an element to appear but the change to the DOM might not happen immediately.

const button = screen.getByRole('button', { name: 'Click Me' })

fireEvent.click(button)

await screen.findByText('Clicked once')

fireEvent.click(button)

await screen.findByText('Clicked twice')

waitFor

function waitFor<T>(

callback: () => T | Promise<T>,

options?: {

container?: HTMLElement

timeout?: number

interval?: number

onTimeout?: (error: Error) => Error

mutationObserverOptions?: MutationObserverInit

}

): Promise<T>

When in need to wait for any period of time you can use waitFor, to wait for your expectations to pass. Here's a simple example:

// ...

// Wait until the callback does not throw an error. In this case, that means

// it'll wait until the mock function has been called once.

await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1))

// ...

waitFor may run the callback a number of times until the timeout is reached. Note that the number of calls is constrained by the timeout and interval options.

This can be useful if you have a unit test that mocks API calls and you need to wait for your mock promises to all resolve.

If you return a promise in the waitFor callback (either explicitly or implicitly with async syntax), then the waitFor utility will not call your callback again until that promise rejects. This allows you to waitFor things that must be checked asynchronously.

The default container is the global document. Make sure the elements you wait for are descendants of container.

The default interval is 50ms. However it will run your callback immediately before starting the intervals.

The default timeout is 1000ms.

The default onTimeout takes the error and appends the container's printed state to the error message which should hopefully make it easier to track down what caused the timeout.

The default mutationObserverOptions is {subtree: true, childList: true, attributes: true, characterData: true} which will detect additions and removals of child elements (including text nodes) in the container and any of its descendants. It will also detect attribute changes. When any of those changes occur, it will re-run the callback.

waitForElementToBeRemoved

function waitForElementToBeRemoved<T>(

callback: (() => T) | T,

options?: {

container?: HTMLElement

timeout?: number

interval?: number

onTimeout?: (error: Error) => Error

mutationObserverOptions?: MutationObserverInit

}

): Promise<void>

To wait for the removal of element(s) from the DOM you can use waitForElementToBeRemoved. The waitForElementToBeRemoved function is a small wrapper around the waitFor utility.

The first argument must be an element, array of elements, or a callback which returns an element or array of elements.

Here is an example where the promise resolves because the element is removed:

const el = document.querySelector('div.getOuttaHere')

waitForElementToBeRemoved(document.querySelector('div.getOuttaHere')).then(() =>

console.log('Element no longer in DOM')

)

el.setAttribute('data-neat', true)

// other mutations are ignored...

el.parentElement.removeChild(el)

// logs 'Element no longer in DOM'

waitForElementToBeRemoved will throw an error if the first argument is null or an empty array:

waitForElementToBeRemoved(null).catch((err) => console.log(err))

waitForElementToBeRemoved(queryByText(/not here/i)).catch((err) =>

console.log(err)

)

waitForElementToBeRemoved(queryAllByText(/not here/i)).catch((err) =>

console.log(err)

)

waitForElementToBeRemoved(() => getByText(/not here/i)).catch((err) =>

console.log(err)

)

// Error: The element(s) given to waitForElementToBeRemoved are already removed. waitForElementToBeRemoved requires that the element(s) exist(s) before waiting for removal.

The options object is forwarded to waitFor.