Unify "Firing Events" page

[afontcu]

Same thing as #485.

Event firing utilities are mostly "universal", so they could live above DTL docs.

[MatanBobi]

I'm up for this one :)

[MatanBobi]

Hi @afontcu, @kentcdodds.
I saw Kent's tweet a few days ago about "how to know which event to fire".

Do you think a reference to this app or maybe even gathering up this to an example page is worth doing within this task?

Also, do you think we should build a "General"/"Universal" section? Or do you think it's related to "Getting Started"?

[afontcu]

Hi! 👋

Actually, we might want to put this on hold. It looks like user-event is going to be merged into DOM Testing Lib (testing-library/dom-testing-library#616). If that happens, then docs should tell about user-event events!

[MatanBobi]

No worries, so lets put this one on hold until user-event will get merged and then I'll work on it..
I'll ask for something else from the project :)

[kentcdodds]

I think we're ready to start getting PRs ready to document user event as an official export to @testing-library/dom (importable via import {userEvent} from '@testing-library/dom')

Most of the docs from the original repo can be copied, but there are some improvements I think we should make:

1. No test-ids
2. If we can help it, less contrived examples. We can use imaginary components (similar to the "Tooltip" component I'm using in the hover example)

Off the top of my head, here are some of the differences (though someone should probably do an accuracy check with the PR testing-library/dom-testing-library#616):

1. toggleSelectOptions has been removed in favor of deselectOptions/selectOptions
2. type will now automatically close modifiers (unless skipAutoClose is specified)
3. type no longer supports allAtOnce (people should use paste which is coming soon)
4. blur and focus are new supported events
5. EVERYTHING is now async (user's can't synchronously fire one event after the other, so neither should our tests)
6. type now supports {del} (delete forwards) and {selectall} (and incidentally, clear is basically a shortcut for this)

I'm sure there are things I'm missing, but if someone could get this started, that would be phenomenal!

[nickserv]

@kentcdodds I've added most of these changes to user-event's PRIORITY label but 2, 4, and 6 are missing issues. Would you like me to create issues for them, or should we handle them as part of testing-library/dom-testing-library#616 instead?

[afontcu]

Thanks, Kent! That's great news.

If we can help it, less contrived examples. We can use imaginary components (similar to the "Tooltip" component I'm using in the hover example)

Totally agree. If possible, all code examples in docs should be based on "real" components, instead of foo, bar and so on. Bonus points if we unveil concepts and feature by using and growing the same component. It'd mean less cognitive overhead for readers.

• EVERYTHING is now async (user's can't synchronously fire one event after the other, so neither should our tests)

I gotta say this makes me extremely happy – one less difference to worry about between React Testing Lib and Vue Testing Lib ❤️

---

I wonder if docs should still mention fireEvent for advanced use cases (at the end of the page or something). I'd say userEvent will not cover each case on day 1, so mentioning that fireEvent is there might make sense.

[kentcdodds]

@nickmccurdy, only bug fixes will go into user-event for the next little while. No new features or even improvements to "correctness".

@afontcu, I agree. fireEvent should definitely still be documented for advanced use cases and edge cases. But we should consider user event as the default eventing mechanism.

[nickserv]

@kentcdodds Would you like me to start creating/moving issues to dom-testing-library now or wait a bit?

[kentcdodds]

Yeah, let's move everything over. But in progress work should go to my branch and not the master branch.

[nickserv]

Migrated issues to user-event label in dom-testing-library.