[userEvent/fireEvent]: fireEvent docs say to use userEvent, but all React code samples use fireEvent

[greyscaled]

Description:

Hey there 👋 - our team is newer to testing-library/react, and just had a bit of confusion in PR review whereby we went back and forth on whether to use fireEvent or userEvent.

All of the code examples in the react documentation:

https://testing-library.com/docs/react-testing-library/example-intro

https://testing-library.com/docs/react-testing-library/api/#asfragment

https://testing-library.com/docs/react-testing-library/cheatsheet/

use fireEvent, but then my colleague saw this:

from the core API https://testing-library.com/docs/dom-testing-library/api-events

We're wondering if maybe some of the code examples in the React documentation should use userEvent, given that the API docs for fireEvent give an impression that userEvent is more useful in most projects.

Thanks!

To Reproduce:

1. Observe all code samples in https://testing-library.com/docs/react-testing-library/intro use fireEvent
2. Observe fireEvent API documentation recommends userEvent

Expected behavior:

The userEvent API is present in React code samples

Screenshots:

N/A

Desktop:

N/A

Smartphone:

N/A

[greyscaled]

Our thought was that maybe the code samples need an update - we're unsure, but just wanted to point out our initial confusion on this topic. Thanks for taking a look!

Perhaps the primary location for it would be in the cheatsheet? Or at least a disclaimer in the cheatsheet?

[jsjoeio]

Yes! As @vapurrmaid said, we were confused on which should be used. We're more than happy to raise a PR to update the docs!

[MatanBobi]

Hi @vapurrmaid and @jsjoeio, thanks for taking the time to open this :)
This is actually on purpose, we didn't want to "couple" both of the libraries as this ability is available even without use-event.
The user-event page actually contains React examples so I think it's best to keep it that way.
I'm keeping this one open to see if anyone has another insight on this.
Thanks again!

[ph-fritsche]

We should reconsider this when #980 is merged

[MatanBobi]

@ph-fritsche
Now that #980 is merged, we can talk about this one.
Why do you think we should reconsider it?

[ph-fritsche]

I've got the impression that more people than we probably like to admit do not take the time to read the docs. They take the first example that vaguely might depict their problem and copy it into their test.
As soon as the test shows a check mark, they can no longer be bothered with the question what their test actually verifies.
A lot of the questions on Discord and Stackoverflow are not how to use the tools correctly or how the implementation should be improved but how to make the test pass.

I think a bad test is worse than no test, as the false confidence gained per this test might present another obstacle in rewriting the component under test.

We won't be able to change how people approach this, but we might be able to steer them in the right direction by presenting them best practices at first glance.
For most use cases user-event is the right choice because what most people seem to think when writing their tests is something along "And if the user clicks...". And when they write their tests with fireEvent, just copying the Event.type from their implementation, and later on they discover that user-event is recommended and they switch one for the other, they get confused because userEvent.click does not trigger their click event handler although fireEvent.click did. (There are numerous issues and Discord messages proving this point.)
So I think it might be better to show everybody examples using user-event and rely on the few people, who do have a use case for it, to actually read the docs and discover that there is also a low-level API for them to just dispatch events of their choosing without following a user interaction workflow.