|
| 1 | +# Firing Events |
| 2 | + |
| 3 | +<!-- > **Note** |
| 4 | +> |
| 5 | +> Most projects have a few use cases for `fire_event`, but the majority of the time you should probably use `testing-library-user-event`. --> |
| 6 | + |
| 7 | +## `fire_event` |
| 8 | + |
| 9 | +```rust,ignore |
| 10 | +use testing_library_dom::{EventType, FireEventError}; |
| 11 | +use web_sys::EventTarget; |
| 12 | +
|
| 13 | +fn fire_event<E: EventType>(node: &EventTarget, event: &E) -> Result<bool, FireEventError>; |
| 14 | +``` |
| 15 | + |
| 16 | +Fire DOM events. |
| 17 | + |
| 18 | +```rust,ignore |
| 19 | +// HTML: <button>Submit</button> |
| 20 | +
|
| 21 | +use testing_library_dom::{get_by_text, fire_event}; |
| 22 | +use web_sys::MouseEvent; |
| 23 | +
|
| 24 | +let event = MouseEvent::new("click"); |
| 25 | +event.set_bubbles(true); |
| 26 | +event.set_cancelable(true); |
| 27 | +
|
| 28 | +fire_event( |
| 29 | + get_by_text(&container, "Submit") |
| 30 | + .expect("Get should succeed.") |
| 31 | + .expect("Get should return an element."), |
| 32 | + &event, |
| 33 | +).expect("Event should be fired."); |
| 34 | +``` |
| 35 | + |
| 36 | +## `FireEvent::[<event_name>]` |
| 37 | + |
| 38 | +```rust,ignore |
| 39 | +fn [<event_name>](node: &EventTarget, event_properties: [<EventInit>]) -> Result<bool, CreateOrFireEventError>; |
| 40 | +``` |
| 41 | + |
| 42 | +Convenience methods for firing DOM events. Check out `src/events.rs` for a full list as well as default event proprties. |
| 43 | + |
| 44 | +<!-- TODO: target, data transfer --> |
| 45 | + |
| 46 | +### Keyboard events |
| 47 | + |
| 48 | +There are three event types related to keyboard input - `keyPress`, `keyDown`, and `keyUp`. When firing these you need to reference an element in the DOM and the key you want to fire. |
| 49 | + |
| 50 | +```rust,ignore |
| 51 | +use testing_library_dom::FireEvent; |
| 52 | +use web_sys::KeyboardEventInit; |
| 53 | +
|
| 54 | +let init = KeyboardEventInit::new(); |
| 55 | +init.set_key("Enter"); |
| 56 | +init.set_code("Enter"); |
| 57 | +init.set_char_code(13); |
| 58 | +FireEvent::key_down(&dom_node, &init).expect("Event should be fired."); |
| 59 | +
|
| 60 | +
|
| 61 | +let init = KeyboardEventInit::new(); |
| 62 | +init.set_key("A"); |
| 63 | +init.set_code("KeyA"); |
| 64 | +FireEvent::key_down(&dom_node, &init).expect("Event should be fired."); |
| 65 | +``` |
| 66 | + |
| 67 | +You can find out which key code to use at https://www.toptal.com/developers/keycode. |
| 68 | + |
| 69 | +## `CreateEvent::[<event_name>]` |
| 70 | + |
| 71 | +```rust,ignore |
| 72 | +fn [<event_name>](node: &EventTarget, event_properties: [<EventInit>]) -> Result<[<Event>], CreateOrFireEventError>; |
| 73 | +``` |
| 74 | + |
| 75 | +Convenience methods for creating DOM events that can then be fired by `fire_event`, allowing you to have a reference to the event created: this might be useful if you need to access event properties that cannot be initiated programmatically (such as [`time_stamp`](https://docs.rs/web-sys/latest/web_sys/struct.Event.html#method.time_stamp)). |
| 76 | + |
| 77 | +```rust,ignore |
| 78 | +use testing_library_dom::{CreateEvent, fire_event}; |
| 79 | +use web_sys::MouseEventInit; |
| 80 | +
|
| 81 | +let init = MouseEventInit::new(); |
| 82 | +init.set_button(2); |
| 83 | +let my_event = CreateEvent::click(&node, &init).expect("Event should be created."); |
| 84 | +
|
| 85 | +fire_event(&node, &my_event).expect("Event should be fired."); |
| 86 | +
|
| 87 | +// `my_event.time_stamp()` can be accessed just like any other properties from `my_event`. |
| 88 | +// Note: The access to the events created by `create_event` is based on the native event API. |
| 89 | +// Therefore, native properties of HTML Event object (e.g. `timeStamp`, `cancelable`, `type`) should be set using `Object.defineProperty`. |
| 90 | +// For more info see: https://developer.mozilla.org/en-US/docs/Web/API/Event. |
| 91 | +``` |
| 92 | + |
| 93 | +## `create_event` |
| 94 | + |
| 95 | +```rust,ignore |
| 96 | +use testing_library_dom::{CreateEventError, EventType}; |
| 97 | +use web_sys::EventTarget; |
| 98 | +
|
| 99 | +fn create_event<E: EventType>( |
| 100 | + event_name: &str, |
| 101 | + node: &EventTarget, |
| 102 | + init: Option<E::Init>, |
| 103 | + options: CreateEventOptions<E>, |
| 104 | +) -> Result<E, CreateEventError>; |
| 105 | +
|
| 106 | +struct CreateEventOptions<'a, E: EventType> { |
| 107 | + default_init: Option<&'a DefaultInitFn<E>>, |
| 108 | +} |
| 109 | +
|
| 110 | +type DefaultInitFn<E> = dyn Fn(&<E as EventType>::Init); |
| 111 | +``` |
| 112 | + |
| 113 | +Create DOM events. |
| 114 | + |
| 115 | +```rust,ignore |
| 116 | +use testing_library_dom::{CreateEventOptions, create_event}; |
| 117 | +use web_sys::{InputEvent, InputEventInit}; |
| 118 | +
|
| 119 | +let init = InputEventInit::new(); |
| 120 | +init.set_data(Some("a")); |
| 121 | +let event = create_event::<InputEvent>( |
| 122 | + "input", |
| 123 | + &input, |
| 124 | + Some(&init), |
| 125 | + CreateEventOptions::default() |
| 126 | +).expect("Event should be created."); |
| 127 | +``` |
0 commit comments