Merge into testing libraries and recommend over fireEvent

[nickmccurdy]

Now that this package is mentioned in the testing library docs, it would be nice to expand it enough to be recommended over fireEvent in most cases and include it in the original packages. We should think about what common user interactions are missing that are tricky to implement with fireEvent. Other testing tools like Cypress could be good inspiration.

[riotrah]

Agreed, user-level abstractions are key to testing-library

[Belco90]

To be honest, the way user-event handles the events is how I expected testing-library to handle them the first time I use it. I think this is a good idea.

[Gpx]

I think the end goal of this project is to be included in the testing libraries. For now, I don't think it's mature enough to replace fireEvent

[kentcdodds]

This is definitely an eventual goal, but I feel like we're a long way from that goal. There's a lot of work to be done and I'm afraid that I've just about used up my bandwidth on this project. If anyone else would like to step in and manage the project from here they're more than welcome.

[nickmccurdy]

I'd be happy to help out, but the three issues I originally mentioned have already been fixed, and I'm not sure what else we need at this point. Are there any specific issues, broad goals, or non-functional requirements you'd like us to meet before this is merged?

[kentcdodds]

All of the existing issues are a good start :)

And I just keep getting this feeling that this package really doesn't quite deliver on what it promises 😬

[nickmccurdy]

The main blocker currently is getting async events implemented in a way that fixes this issue.

[cevr]

Honestly, I would be against this. From my experience at work, user-event is incredibly unreliable (almost every update either fixes or breaks something). fireEvent is much more barebones, but it's solid.

Having the option to use both would be ideal IMO!

EDIT: After further investigation, I believe the problem is material-ui being unreliable in testing environments rather than user-event.

[eps1lon]

EDIT: After further investigation, I believe the problem is material-ui being unreliable in testing environments rather than user-event.

Happy to hear your issues out and how you determined that the issue is with one library and not the one. We' re using testing-library internally and I can't recall having to refactor tests since we switched.

Though we shouldn't replace fireEvent. These low-level events are still required for component libraries. Especially since fire-event is quite opinionated when it comes to how user-agents are supposed to behave.

And user-event is still polyfilling some shortcomings of older JSDOM versions (e.g. focus doesn't require any library attention. It should just call element.focus()). If it is only targetted at that environment then that's another reason to not replace fireEvent.

Adding it is fine, but not replacing. These tools are not equivalent.

[nickmccurdy]

Though we shouldn't replace fireEvent.

As far as I remember @kentcdodds' plan a few months ago was to add userEvent as a top level export without actually removing the fireEvent export (so replace wasn't the right word, I updated the issue). We might recommend userEvent over fireEvent in the docs or add warnings to make it clear that userEvent is a better approach when possible (similarly to how we recommend semantic queries like getByLabelText when possible).

We'd still need to at least keep fireEvent around for native events not handled by userEvent, unless that was migrated to a new abstraction under the userEvent API like userEvent (as a top level function), userEvent.fire, userEvent.native, or userEvent.custom. As much as I'd like to just have one API, I'm not sure if merging them would be too confusing of a migration path, though we could make it easier with a codemod (like how React extracted factories and prop types into separate packages).

And user-event is still polyfilling some shortcomings of older JSDOM versions (e.g. focus doesn't require any library attention. It should just call element.focus()).

Should we automatically detect the JSDOM version and only apply fixes in broken versions? Alternatively we can set up deprecation policies for older versions of JSDOM (which should probably be based off popular tools like create-react-app and Jest) and just remove fixes for versions that are no longer supported. That could possibly reduce the number of issues related to JSDOM as well.

[ph-fritsche]

Any further discussion about merging this into @testing-library/dom can be continued in #669 .