You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
For common events like `press` or `type` it's recommended to use [User Event API](UserEvent.md) as it offers
330
+
more realistic event simulation by emitting a sequence of events with proper event objects that mimic React Native runtime behavior.
331
+
332
+
Use Fire Event for cases not supported by User Event and for triggering event handlers on composite components.
333
+
:::
350
334
351
-
Invokes a given event handler (whether native or custom) on the element, bubbling to the root of the rendered tree.
335
+
`fireEvent` API allows you to trigger all kind of event handlers on both host and composite components. It will try to invoke a single event handler traversing the component tree bottom-up from passed element and trying to find enabled event handler named `onXxx` when `xxx` is the name of the event passed.
336
+
337
+
Unlike User Event, this API does not automatically pass event object to event handler, this is responsibility of the user to construct such object.
It is recommended to use the User Event [`press()`](UserEvent.md#press) helper instead as it offers more realistic simulation of press interaction, including pressable support.
393
+
:::
394
+
405
395
Invokes `press` event handler on the element or parent element in the tree.
It is recommended to use the User Event [`type()`](UserEvent.md#type) helper instead as it offers more realistic simulation of text change interaction, including key-by-key typing, element focus, and other editing events.
429
+
:::
430
+
437
431
Invokes `changeText` event handler on the element or parent element in the tree.
Copy file name to clipboardExpand all lines: website/docs/UserEvent.md
+30-11Lines changed: 30 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -5,16 +5,31 @@ title: User Event
5
5
6
6
### Table of contents
7
7
8
-
-[`userEvent.setup`](#usereventsetup)
8
+
-[Comparison with Fire Event API](#comparison-with-fire-event-api)
9
+
-[`setup()`](#setup)
9
10
-[Options](#options)
10
11
-[`press()`](#press)
11
12
-[`longPress()`](#longpress)
13
+
-[Options](#options-1)
12
14
-[`type()`](#type)
13
-
-[Options:](#options-1)
15
+
-[Options](#options-2)
14
16
-[Sequence of events](#sequence-of-events)
15
17
18
+
:::caution
19
+
User Event API is in beta stage.
16
20
17
-
## `userEvent.setup`
21
+
This means that we plan to keep the public API signatures to remain stable, but we might introduce breaking behavioural changes, e.g. changing the ordering or timing of emitted events, without a major version update. Hopefully, well written code should not rely on such specific details.
22
+
:::
23
+
24
+
## Comparison with Fire Event API
25
+
26
+
Fire Event is our original event simulation API. It offers ability to invoke **any event handler** declared on **either host or composite elements**. If the element does not have `onEventName` event handler for passed `eventName` event, or the element is disabled, Fire Event will traverse up the component tree, looking for event handler on both host and composite elements along the way. By default it will **not pass any event data**, but the user might provide it in the last argument.
27
+
28
+
In contrast, User Event provides realistic event simulation for main user interactions like `press` or `type`. Each of the interactions will trigger a **sequence of events** corresponding to React Native runtime behavior. These events will be invoked **only on host elements**, and **will automatically receive event data** corresponding to each event.
29
+
30
+
If User Event supports given interaction you should always prefer it over Fire Event counterpart, as it will make your tests much more realistic and hence reliable. In other cases, e.g. when event is not supported by User Event, or when invoking event handlers on composite elements, you have to use Fire Event as the only available option.
31
+
32
+
## `setup()`
18
33
19
34
```ts
20
35
userEvent.setup(options?: {
@@ -28,11 +43,11 @@ Example
28
43
const user =userEvent.setup();
29
44
```
30
45
31
-
Creates User Event instances which can be used to trigger events.
46
+
Creates an User Event object instance which can be used to trigger events.
32
47
33
48
### Options
34
-
-`delay` - controls the default delay between subsequent events, e.g. keystrokes, etc.
35
-
-`advanceTimers` - time advancement utility function that should be used for fake timers. The default setup handles both real and Jest fake timers.
49
+
-`delay` - controls the default delay between subsequent events, e.g. keystrokes.
50
+
-`advanceTimers` - time advancement utility function that should be used for fake timers. The default setup handles both real timers and Jest fake timers.
36
51
37
52
38
53
## `press()`
@@ -49,7 +64,7 @@ const user = userEvent.setup();
49
64
awaituser.press(element);
50
65
```
51
66
52
-
This helper simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()` which is a simpler API that will only call the `onPress` prop, this simulates the entire press event in a more realistic way by reproducing what really happens when a user presses an interface view. This will trigger additional events like `pressIn` and `pressOut`.
67
+
This helper simulates a press on any pressable element, e.g. `Pressable`, `TouchableOpacity`, `Text`, `TextInput`, etc. Unlike `fireEvent.press()` which is a simpler API that will only call the `onPress` prop, this function simulates the entire press interaction in a more realistic way by reproducing event sequence emitted by React Native runtime. This helper will trigger additional events like `pressIn` and `pressOut`.
53
68
54
69
## `longPress()`
55
70
@@ -68,6 +83,9 @@ await user.longPress(element);
68
83
69
84
Simulates a long press user interaction. In React Native the `longPress` event is emitted when the press duration exceeds long press threshold (by default 500 ms). In other aspects this actions behaves similar to regular `press` action, e.g. by emitting `pressIn` and `pressOut` events. The press duration is customisable through the options. This should be useful if you use the `delayLongPress` prop. When using real timers this will take 500 ms so it is highly recommended to use that API with fake timers to prevent test taking a long time to run.
70
85
86
+
### Options
87
+
-`duration` - duration of the press in miliseconds. Default value is 500 ms.
88
+
71
89
## `type()`
72
90
73
91
```ts
@@ -90,7 +108,7 @@ This helper simulates user focusing on `TextInput` element, typing `text` one ch
90
108
91
109
This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
92
110
93
-
### Options:
111
+
### Options
94
112
- `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
95
113
- `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
96
114
@@ -100,14 +118,14 @@ The sequence of events depends on `multiline` prop, as well as passed options.
100
118
101
119
Events will not be emitted if `editable` prop is set to `false`.
102
120
103
-
Entering the element:
121
+
**Entering the element**:
104
122
- `pressIn` (optional)
105
123
- `focus`
106
124
- `pressOut` (optional)
107
125
108
126
The `pressIn` and `pressOut` events are sent by default, but can be skipped by passing `skipPress: true` option.
109
127
110
-
Typing (for each character):
128
+
**Typing (for each character)**:
111
129
- `keyPress`
112
130
- `textInput` (optional)
113
131
- `change`
@@ -116,9 +134,10 @@ Typing (for each character):
116
134
117
135
The `textInput` event is sent only for mutliline text inputs.
118
136
119
-
Leaving the element:
137
+
**Leaving the element**:
120
138
- `submitEditing` (optional)
121
139
- `endEditing`
122
140
- `blur`
123
141
124
142
The `submitEditing` event is skipped by default. It can sent by setting `submitEditing: true` option.
0 commit comments