fireEventByName function Null safety UserActions

bool fireEventByName(
  1. String eventName,
  2. Element element,
  3. [Map? eventProperties]
)

Fires a DOM Event using the eventName on the provided element.

The eventName must be one of the keys found in the JS eventMap.

NOTE:

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

Read more about interactions vs. events

Dart / JS API Parity

Since Dart doesn't support anonymous objects that can act as both a Map and a function like the JS fireEvent can, this function acts as a proxy for:

// JS API
fireEvent.click(someElement, {'button': 2});

Where the Dart API equivalent of the above call would be:

// Dart API
fireEventByName('click', someElement, {'button': 2});

Warning About Errors

Unlike the JS API, any uncaught errors thrown during event propagation will get rethrown. This helps surface errors that could otherwise go unnoticed since they aren't printed to the terminal when running tests.

See: testing-library.com/docs/dom-testing-library/api-events/#fireeventeventname

Implementation

bool fireEventByName(String eventName, Element element, [Map? eventProperties]) {
  if (!JsBackedMap.fromJs(_fireEventObj).keys.contains(eventName)) {
    throw ArgumentError.value(eventName, 'eventName');
  }

  final jsFireEventByNameFn =
      JsBackedMap.fromJs(_fireEventObj)[eventName] as bool Function(Element, [/*JsObject*/ dynamic]);

  if (eventProperties == null) {
    return eventHandlerErrorCatcher(() => jsFireEventByNameFn(element));
  }

  return eventHandlerErrorCatcher(() => jsFireEventByNameFn(element, jsifyAndAllowInterop(eventProperties)));
}