Async Utilities

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 action. (See the guide to testing disappearance.)

`wait`

function wait(
  callback?: () => void,
  options?: {
    timeout?: number
    interval?: number
  }
): Promise<void>

When in need to wait for non-deterministic periods of time you can use wait, to wait for your expectations to pass. The wait function is a small wrapper around the wait-for-expect module. Here's a simple example:

// ...
// Wait until the callback does not throw an error. In this case, that means
// it'll wait until we can get a form control with a label that matches "username".
await wait(() => getByLabelText(container, 'username'))
getByLabelText(container, 'username').value = 'chucknorris'
// ...

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.

The default callback is a no-op function (used like await wait()). This can be helpful if you only need to wait for one tick of the event loop (in the case of mocked API calls with promises that resolve immediately).

The default timeout is 4500ms which will keep you under Jest's default timeout of 5000ms.

The default interval is 50ms. However it will run your callback immediately on the next tick of the event loop (in a setTimeout) before starting the intervals.

`waitForElement`

function waitForElement<T>(
  callback: () => T,
  options?: {
    container?: HTMLElement
    timeout?: number
    mutationObserverOptions?: MutationObserverInit
  }
): Promise<T>

When in need to wait for DOM elements to appear, disappear, or change you can use waitForElement. The waitForElement function is a small wrapper around the MutationObserver.

Here's a simple example:

// ...
// Wait until the callback does not throw an error and returns a truthy value. In this case, that means
// it'll wait until we can get a form control with a label that matches "username".
// The difference from `wait` is that rather than running your callback on
// an interval, it's run as soon as there are DOM changes in the container
// and returns the value returned by the callback.
const usernameElement = await waitForElement(
  () => getByLabelText(container, 'username'),
  { container }
)
usernameElement.value = 'chucknorris'
// ...

You can also wait for multiple elements at once:

const [usernameElement, passwordElement] = await waitForElement(
  () => [
    getByLabelText(container, 'username'),
    getByLabelText(container, 'password'),
  ],
  { container }
)

Using MutationObserver is more efficient than polling the DOM at regular intervals with wait. This library sets up a 'mutationobserver-shim' on the global window object for cross-platform compatibility with older browsers and the jsdom that is usually used in Node-based tests.

The default container is the global document. Make sure the elements you wait for will be attached to it, or set a different container.

The default timeout is 4500ms which will keep you under Jest's default timeout of 5000ms.

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.

`waitForDomChange`

function waitForDomChange<T>(options?: {
  container?: HTMLElement
  timeout?: number
  mutationObserverOptions?: MutationObserverInit
}): Promise<T>

When in need to wait for the DOM to change you can use waitForDomChange. The waitForDomChange function is a small wrapper around the MutationObserver.

Here is an example where the promise will be resolved because the container is changed:

const container = document.createElement('div')
waitForDomChange({ container })
  .then(() => console.log('DOM changed!'))
  .catch(err => console.log(`Error you need to deal with: ${err}`))
container.append(document.createElement('p'))
// if 👆 was the only code affecting the container and it was not run,
// waitForDomChange would throw an error

The promise will resolve with a mutationsList which you can use to determine what kind of a change (or changes) affected the container

const container = document.createElement('div')
container.setAttribute('data-cool', 'true')
waitForDomChange({ container }).then(mutationsList => {
  const mutation = mutationsList[0]
  console.log(
    `was cool: ${mutation.oldValue}\ncurrently cool: ${
      mutation.target.dataset.cool
    }`
  )
})
container.setAttribute('data-cool', 'false')
/*
  logs:
    was cool: true
    currently cool: false
*/

The default container is the global document. Make sure the elements you wait for will be attached to it, or set a different container.

The default timeout is 4500ms which will keep you under Jest's default timeout of 5000ms.

`waitForElementToBeRemoved`

function waitForElementToBeRemoved<T>(
  callback: () => T,
  options?: {
    container?: HTMLElement
    timeout?: number
    mutationObserverOptions?: MutationObserverInit
  }
): Promise<T>

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

The callback must return the pre-existing element or array of elements that are expected to be removed.

Here is an example where the promise resolves with true 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 when the provided callback does not return an element.

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

// 'The callback function which was passed did not return an element
// or non-empty array of elements.
// waitForElementToBeRemoved requires that the element(s) exist
// before waiting for removal.'

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

The default timeout is 4500ms which will keep you under Jest's default timeout of 5000ms.

Testing Library

DOM Testing Library

React Testing Library

ReasonReact Testing Library

Native Testing Library

Vue Testing Library

`wait`

`waitForElement`

`waitForDomChange`

`waitForElementToBeRemoved`