UserActions topic

Firing Events

NOTE:

Most projects have a few use cases for fireEvent, but the majority of the time you should probably use UserEvent methods.

Interactions vs. events

Based on the Guiding Principles, your test should resemble how users interact with your code (component, page, etc.) as much as possible. With this in mind, you should know that fireEvent isn't exactly how the user interacts with your application, but it's close enough for most scenarios.

Consider fireEvent when providing it a MouseEvent('click') event - it creates a click event and dispatches that event on the given DOM node. This works properly for most situations when you simply want to test what happens when your element is clicked, but when the user actually clicks your element in the browser, these are the events that are typically fired (in order):

  • mouseOver
  • mouseMove
  • mouseDown
  • element.focus() (if that element is focusable)
  • mouseUp
  • click

And then, if that element happens to be a child of a <label>, then it will also move focus to the form control that the label is labeling. So even though all you really are trying to test is the click handler, by simply using fireEvent you're missing out on several other potentially important events the user is firing along the way.

Again, most of the time this isn't critical for your tests, and the trade-off of simply using fireEvent is sometimes worth it. However, if you want your test to actually simulate everything that happens when a real user clicks a real element in the browser - you should use UserEvent methods.

Libraries

user_event UserActions
A library that provides more advanced simulation of browser interactions than the built-in fireEvent method.

Classes

UserEvent UserActions
Test utility methods that provide more advanced simulation of browser interactions than the fireEvent function.

Functions

fireEvent(Element element, Event event) → bool UserActions
Fires a DOM event on the provided element.
fireEventByName(String eventName, Element element, [Map? eventProperties]) → bool UserActions
Fires a DOM Event using the eventName on the provided element.