Proper use of async UserEvent methods

[brandon-lile]

My team was working on the upgrade from react-testing-library/user-event@13.5.0 to 14.0.4 this morning and we ran into a bit of a misunderstanding when it comes to the new asynchronous functionality of userEvent.anyApi.

I went through and read the initial issue (#504) as well as the PRs that referenced it and it doesn't seem like there was ever a clear resolution or documentation on how they intend you use it? There was some good back and forth on proper testing methodology between the team, then the issue went dead, and finally it was implemented (somehow) without any documentation that I can find.

Is the idea that await userEvent.anyApi resolves after config.delay (this appears to be something intended for multiple inputs) or is there some other gating factor? Maybe a better way to put the question is What is userEvent.anyApi waiting for before resolving, and how can I leverage the new async nature of it to write better tests?

[ph-fritsche]

If you get const user = userEvent.setup() at the beginning of the test and then await user.anyApi() for simulating user interaction, you probably won't need to bother what happens under the hood in user-event, the DOM implementation and the JS framework of your choice. I recommend @typescript-eslint/no-floating-promises.

The real user interaction happens concurrently to any code running. The browser implements a UI on top of the DOM and this DOM is programmatically available to JS code which itself runs in the Event Loop. The concurrent real user interactions causes the browser to dispatch events as new macrotasks on the Event Loop.
When a JS test runner like Jest executes JS tests which assert behavior of JS code in event handlers and framework render functions, everything happens in the Event Loop and none of it has access to a "real UI".
We try our best to mitigate this issue and provide an API that feels like interacting like a user.

The asynchronous implementation allows us to push code to the Event Loop as a new micro- or macro-task so that it runs after e.g. an event handler, a render, or after we accessed an asynchronous API.
The await in your test code allows this implementation to complete before you run assertions on the result.

[brandon-lile]

Thank you very much for the information Phillipp! That was very insightful and after reading through the Event Loop link you provided, I think I have a bit of a better understanding. So just making sure I fully understand: userEvent.anyApi is placing a message on the event loop, and will resolve once that event is processed by the event loop?

Just to verify that I've understood this I would like to walk through an example I've built below. In our SimpleComponent.tests.tsx test we are rendering our SimpleComponent and typing cool input to text field. When we do the await user.type(...), the testing library is going to place a change event message onto the event loop. Once the event loop processes the message it will call the handleChange function found in SimpleComponent. After it has run through the handleChange function (and anything else attached to the change event) it resolve the user.type promise. Note: the handleChange function called a state update. This in itself was another event that would have been placed on the event loop and not processed until after the user.type was resolved.

Does that sound correct? Or am I still missing something?

SimpleComponent.tsx

export const SimpleComponent = () => {
    const [someBool, setSomeBool] = useState<boolean>(false)

    const handleChange = () => {
        setSomeBool(true)
    }

    return <TextInput data-testId={'cool-input'} onChange={handleChange} />
}

SimpleComponent.tests.tsx

it('allows us to type cool', async () => {
    const user = userEvent.setup()
    const { screen } = render(<SimpleComponent />)

    await user.type(screen.getByTestId('cool-input'), 'cool')
})

[ph-fritsche]

If you write await user.type(element, 'cool'), this library will dispatch multiple events which would happen when a user clicks the element and types "cool". The dispatching and native event handling itself is synchronous, React adds native listeners to the controlled element and then dispatches SyntheticEvent to your handler accordingly. Between those events this library will manipulate the native elements, so that React and your handlers see the DOM in the same state it would be if the events were the result of a real user interaction.
For the exact implementation you can always have a look at the code.
How this affects your tests is described in "Why You Should Test With User-Event".

[brandon-lile]

Thanks again Phillipp!