User-event: 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]

Would you mind giving me access to organize issues or create a Project board on this repository? I can start triaging existing issues, and we can all use it to keep track of progress for this issue.

[kentcdodds]

Thanks so much for your help! I've added you as a collaborator on the project. Please make sure that you review the other/MAINTAINING.md and CONTRIBUTING.md files (specifically the bit about the commit messages and the git hooks) and familiarize yourself with the code of conduct (we're using the contributor covenant). You might also want to watch the repo (if you're not already) to be notified when someone files an issue/PR. Please continue to make PRs as you feel the need (you can make your branches directly on the repo rather than your fork if you want). Thanks! And welcome to the team :)

[nickmccurdy]

Keeping track of confirmed issues related to this goal in the Roadmap. If you'd like to contribute feel free to pick something off the To Do column that isn't assigned.

[nickmccurdy]

@kentcdodds Did you mean to send a comment? I thought I remembered you typing on on stream.

[kentcdodds]

Haha, yeah, I started typing some ideas of other things we could add, then I changed my mind on them 😅

[kentcdodds]

Ok, after thinking about this and feeling revitalized thanks to @nickmccurdy's personal interest, I'm motivated to making this happen. Let's make this happen, and in the next day or two. We can leave this package without a major version bump (though perhaps we'd do a major version bump akin to https://npm.im/dom-testing-library to announce the deprecation of the package), and we can do a minor version bump to DOM Testing Library when we add the feature.

I'll be working on this for the next day or two. FYI @testing-library/all-maintainers

[diegohaz]

@kentcdodds Happy to hear that! :)
Are you planning to livestream part of that?

[kentcdodds]

Probably. Will be on https://kcd.im/discord

[nickmccurdy]

Closing this since I mostly created it for discussion and we have clearer goals now. We'll keep track of the work needed to prepare for the merge into dom-testing-library in #334.

[nickmccurdy]

We're now working on merging user-event back into dom-testing-library in testing-library/dom-testing-library#616

[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.