Are there any good examples of when waitFor would work and waitForElementToBeRemoved wouldn't in this context? If not, then maybe it shouldn't have equal space on this page.

agree 👍

If not, I wouldn't even mention a "negated" waitFor as an alternative to waitForElementToBeRemoved

I agree, I've removed the waitFor option here ✨

Maybe add an extra assertion to check that it's not present initially?

// element is initially not present...
expect(movieTitle).not.toBeInTheDocument()

Maybe, but I feel that isn't entirely relevant and detracts a little from what we're trying to show in this example. Also, asserting that things don't exist is covered further down on the page.

If we did do that though, there should also be code here to do something that would make the title appear after asserting it isn't here, and I'm not sure it makes sense to get into that here.

We could add a comment saying as much after the assertion, like this:

test('movie title appears', async () => {
 expect(screen.queryByText('the lion king')).not.toBeInTheDocument()
 
 // pretend we do something here that should make the title appear
 const movieTitle = await screen.findByText('the lion king')
 expect(movieTitle).toBeInTheDocument()
})

But I think it might be better to alter the comment in the test to something that makes it clearer that this would be part of a longer test:

Do you think the last suggestion would help, or is there maybe something else we could do to alleviate the confusion or lack of clarity we are hoping to fix by adding this assertion?

I think the first suggestion is much clearer instead of changing the comment tbh

I think the first suggestion is much clearer instead of changing the comment tbh

Fair! In your mind, what is it that is unclear that adding this assertion solves? Or is there something else that makes it so you want it to be added?

On the other hand, you're right with not wanting to have things in here that you'll explain later, so maybe the changed comment is indeed a better option to go with here...

Maybe we can make a full example (like the second suggestion) later on the page? 🤔

I think there's value in keeping the first examples minimal, without having to decipher fake application code. Expanding on the comment and making clear this is a snippet of a larger test should be good.

Okay, this is interesting.

I'm not sure I agree on the statement (I believe using waitFor is more explicit, and helps the test conveying meaning) but that's entirely personal. The question here is whether if docs should showcase two ways of doing the same thing 🤔

If we agree on findBy being simpler and packed with a better error message, then I'd say this is the way docs should suggest 👍

waitFor is useful for other stuff (such as waiting for XHR requests to happen, or other). It might appear somewhere else in docs.

I think this is the last bit that needs some attention, then we can merge!

I see @kentcdodds commented over here that this should receive a callback, not the element directly: testing-library/react-testing-library#673 (comment)

I feel like I've seen that doing it this way works too though, so I'm not sure.

It can either receive a callback, an element, or an array of elements:

https://github.com/testing-library/dom-testing-library/blob/master/types/__tests__/type-tests.ts#L158-L164

https://github.com/testing-library/dom-testing-library/blob/master/types/wait-for-element-to-be-removed.d.ts

might be worth expanding on this section later with a note about working with React, because sometimes the node gets destroyed and replaced, making these types of tests either pass or fail when they shouldn't

I think the waitFor style should also be documented here, particularly for working with React, when the node reference itself is unstable but a retryable query inside a callback would work.

This section can be tightened up. It's unclear what "this" refers to here. Also, we shouldn't assume jest-dom is installed and should mention the null check.