Add async/retryable findBy* and findAllBy* version of the queries

[kentcdodds]

Describe the feature you'd like:

@alexkrolick has brought this up before and we ultimately decided to not go for it at the time, but I've been thinking about it more and I think it's time to revisit the decision.

There are some UI frameworks that are completely async. In my TestingJavaScript.com course when I show how to use dom-testing-library with these, I had to create a fire-event-async.js file to deal with those, but that wasn't enough for mithril's tests because mithril does not re-render on the next tick all the time (for who knows what reason 🤷‍♂️).

The findBy* and findAllBy* variants of the queries would return promises that resolve when the query is satisfied, or timeout after 3500ms or so.

Suggested implementation:

I'm thinking it'd be something like this:

const findByText = (...args) => waitForElement(() => getByText(...args))
const findAllByText = (...args) => waitForElement(() => getAllByText(...args))

Describe alternatives you've considered:

So far the alternative is to have people write this themselves:

const successMessage = await waitForElement(() => getByText(/.*success.*/i))
expect(successMessage).toHaveTextContent('Welcome back Nancy')

That's worked pretty well most of the time, but I think it would be nicer to write that like this:

const successMessage = await findByText(/.*success.*/i)
expect(successMessage).toHaveTextContent('Welcome back Nancy')

Teachability, Documentation, Adoption, Migration Strategy:

We do have query explosion going on and I think the docs could be improved slightly around this to document first the types of queries (label text, text, placeholder, etc), and then the variants (getBy*, queryAllBy*, etc.).

This would be a new feature, so no breaking change/migration strategy necessary.

[alexkrolick]

Feel free to pull in https://github.com/alexkrolick/dom-testing-addon-async

[kentcdodds]

How has that lib been going @alexkrolick? Are you using it? Do you know of anyone else using it? What do you think?

[alexkrolick]

I used it in Puppeteer to simulate Cypress-like retries and it worked pretty well.

The tricky part was more dealing with dist and CJS/ES compatibility, and something about mutation observer being required in the node env when the queries were iterated to do the re-export, which wouldn't matter if it was in core.

[kentcdodds]

I think that it's safe to say we can take a PR to add these queries. I may get to it eventually if nobody else does it first :)

[Tolsee]

Hey @kentcdodds, I can give a try to this(most probably this weekend).

[weyert]

What's the idea just copy over the files from the other repo? I can do that :D

[kentcdodds]

What other files/repo?

[kentcdodds]

Oh, no, this will be implemented as queries instead. Much better.

[alexkrolick]

Yeah, create named functions in queries.js. Don't use the custom wait either, use waitForElement.

[weyert]

Ah okay, I will see if I find the time over the weekend/next week. If anyone wants to work on this don't hesitate to do so :)

[kentcdodds]

I'm working on this as I type this: https://www.youtube.com/watch?v=s0GLe81-9QY&index=2&list=PLV5CVI1eNcJgJCEkMlsqXea6OIF_uV_ub&t=0s

[kentcdodds]

🎉 This issue has been resolved in version 3.18.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀