Clarifying user-event's capabilities vs fire-event

[meatnordrink]

The current intro makes it sounds like user-event can test all valid user interactions, and is a replacement for fire-event in all user-interaction cases. However, in our engineering dept., we've found that this is not the case. For example, to pick a specific value on a slider, we use:

fireEvent.change(screen.getByRole('slider'), { target: { value: '3000' } })

We haven't been able to find any user-event equivalent to this. So unless there's something we're not aware of (and we've posted the question to SO and received no responses), then noting that user-event can not replace fire-event in all cases would improve the clarity and usefulness of the user-event intro.

[ph-fritsche]

user-event is not an equivalent replacement to fireEvent.

fireEvent dispatches DOM events, whereas user-event simulates full
interactions, which may fire multiple events and do additional checks along
the way.

You should use user-event to simulate user interactions.

Like with every other software there are limitations.
You can use fireEvent in these cases, but then you are not testing a user interaction but the handling of a concrete event.

Regarding <input type="range"/> element, see testing-library/user-event#871

[meatnordrink]

@ph-fritsche thanks for the comment!

user-event is not an equivalent replacement to fireEvent.
You should use user-event to simulate user interactions.

Yes, I totally understand this - my last PR for this repo actually resulted in the text you're quoting.

Like with every other software there are limitations.

This is the point that I think would be helpful to make clearer - that user-event is currently limited in the number of user-interactions that it can represent. Even an explicit list of user interactions it's not able to handle (such as the link to testing-library/user-event#871 that you posted), would be helpful.

What's frustrating about the current phrasing is that it makes it sound like you should be able to test all user interactions via user-event, while in reality there are some that you can't - so you need to use fireEvent (even though that means not truly testing interactions).

This leads to devs wasting time trying to figure out how to get user-event to do things it can't - as we did, and as other devs are clearly doing, judging from the comments on user-event#871. An explicit acknowledgment of this up front would save devs time - and a list of what can and can't be tested would be even better.

[meatnordrink]

Great suggestions, @ph-fritsche - I implemented both of them. Feel free to tweak the wording, I just put in exactly what you suggested.

[timdeschryver]

👍 LGTM.
Leaving this for @ph-fritsche for a final review.

[ph-fritsche]

Added missing backticks

[ph-fritsche]

Thanks for helping us improve the docs @meatnordrink ❤️