await-async-utils.md

Enforce promises from async utils to be handled (testing-library/await-async-utils)

Ensure that promises returned by async utils are handled properly.

Rule Details

Testing library provides several utilities for dealing with asynchronous code. These are useful to wait for an element until certain criteria or situation happens. The available async utils are:

• waitFor (introduced since dom-testing-library v7)
• waitForElementToBeRemoved
• wait (deprecated since dom-testing-library v7)
• waitForElement (deprecated since dom-testing-library v7)
• waitForDomChange (deprecated since dom-testing-library v7)

This rule aims to prevent users from forgetting to handle the returned promise from async utils, which could lead to problems in the tests. The promise will be considered as handled when:

• using the await operator
• wrapped within Promise.all or Promise.allSettled methods
• chaining the then method
• chaining resolves or rejects from jest
• it's returned from a function (in this case, that particular function will be analyzed by this rule too)

Examples of incorrect code for this rule:

test('something incorrectly', async () => {
  // ...
  waitFor(() => {});

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

  waitFor(() => {}, { timeout: 100 });

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

  // wrap an async util within a function...
  const makeCustomWait = () => {
    return waitForElementToBeRemoved(() =>
      document.querySelector('div.getOuttaHere')
    );
  };
  makeCustomWait(); // ...but not handling promise from it is incorrect
});

Examples of correct code for this rule:

test('something correctly', async () => {
  // ...
  // `await` operator is correct
  await waitFor(() => getByLabelText('email'));

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

  // `then` chained method is correct
  waitFor(() => {}, { timeout: 100 })
    .then(() => console.log('DOM changed!'))
    .catch((err) => console.log(`Error you need to deal with: ${err}`));

  // wrap an async util within a function...
  const makeCustomWait = () => {
    return waitForElementToBeRemoved(() =>
      document.querySelector('div.getOuttaHere')
    );
  };
  await makeCustomWait(); // ...and handling promise from it is correct

  // using Promise.all combining the methods
  await Promise.all([
    waitFor(() => getByLabelText('email')),
    waitForElementToBeRemoved(() => document.querySelector('div.getOuttaHere')),
  ]);
});

Further Reading

• Async Utilities