0
# Event Simulation
1

2
Fire DOM events to simulate user interactions and test event handling.
3

4
## fireEvent
5

6
Fire a DOM event on an element with optional properties.
7

8
```typescript
9
const fireEvent: FireFunction & FireObject;
10

11
type FireFunction = (element: Node | Document | Window, event: Event) => boolean;
12

13
interface FireObject {
14
  // Mouse events
15
  click(element: Node, options?: {}): boolean;
16
  dblClick(element: Node, options?: {}): boolean;
17
  mouseDown(element: Node, options?: {}): boolean;
18
  mouseUp(element: Node, options?: {}): boolean;
19
  mouseMove(element: Node, options?: {}): boolean;
20
  mouseEnter(element: Node, options?: {}): boolean;
21
  mouseLeave(element: Node, options?: {}): boolean;
22
  mouseOver(element: Node, options?: {}): boolean;
23
  mouseOut(element: Node, options?: {}): boolean;
24
  contextMenu(element: Node, options?: {}): boolean;
25
  
26
  // Keyboard events
27
  keyDown(element: Node, options?: {}): boolean;
28
  keyUp(element: Node, options?: {}): boolean;
29
  keyPress(element: Node, options?: {}): boolean;
30
  
31
  // Form events
32
  change(element: Node, options?: {}): boolean;
33
  input(element: Node, options?: {}): boolean;
34
  submit(element: Node, options?: {}): boolean;
35
  reset(element: Node, options?: {}): boolean;
36
  invalid(element: Node, options?: {}): boolean;
37
  
38
  // Focus events
39
  focus(element: Node, options?: {}): boolean;
40
  blur(element: Node, options?: {}): boolean;
41
  focusIn(element: Node, options?: {}): boolean;
42
  focusOut(element: Node, options?: {}): boolean;
43
  
44
  // Pointer events
45
  pointerDown(element: Node, options?: {}): boolean;
46
  pointerUp(element: Node, options?: {}): boolean;
47
  pointerMove(element: Node, options?: {}): boolean;
48
  pointerOver(element: Node, options?: {}): boolean;
49
  pointerEnter(element: Node, options?: {}): boolean;
50
  pointerLeave(element: Node, options?: {}): boolean;
51
  pointerOut(element: Node, options?: {}): boolean;
52
  pointerCancel(element: Node, options?: {}): boolean;
53
  
54
  // Drag events
55
  dragStart(element: Node, options?: {}): boolean;
56
  drag(element: Node, options?: {}): boolean;
57
  dragEnd(element: Node, options?: {}): boolean;
58
  dragEnter(element: Node, options?: {}): boolean;
59
  dragExit(element: Node, options?: {}): boolean;
60
  dragLeave(element: Node, options?: {}): boolean;
61
  dragOver(element: Node, options?: {}): boolean;
62
  drop(element: Node, options?: {}): boolean;
63
  
64
  // Touch events
65
  touchStart(element: Node, options?: {}): boolean;
66
  touchEnd(element: Node, options?: {}): boolean;
67
  touchMove(element: Node, options?: {}): boolean;
68
  touchCancel(element: Node, options?: {}): boolean;
69
  
70
  // Clipboard events
71
  copy(element: Node, options?: {}): boolean;
72
  cut(element: Node, options?: {}): boolean;
73
  paste(element: Node, options?: {}): boolean;
74
  
75
  // Other events
76
  scroll(element: Node, options?: {}): boolean;
77
  wheel(element: Node, options?: {}): boolean;
78
  select(element: Node, options?: {}): boolean;
79
  load(element: Node, options?: {}): boolean;
80
  error(element: Node, options?: {}): boolean;
81
  // ... and many more
82
}
83
```
84

85
## Usage
86

87
```javascript
88
import {fireEvent, screen} from '@testing-library/dom';
89

90
// Click
91
fireEvent.click(screen.getByRole('button', {name: /submit/i}));
92

93
// Change input value
94
fireEvent.change(screen.getByLabelText('Email'), {
95
  target: {value: 'user@example.com'}
96
});
97

98
// Keyboard events
99
fireEvent.keyDown(screen.getByRole('textbox'), {
100
  key: 'Enter',
101
  code: 'Enter',
102
  charCode: 13
103
});
104

105
// Mouse events
106
fireEvent.mouseDown(element, {clientX: 100, clientY: 100});
107
fireEvent.mouseUp(element);
108

109
// Form submission
110
fireEvent.submit(screen.getByRole('form'));
111

112
// Focus
113
fireEvent.focus(element);
114
fireEvent.blur(element);
115
```
116

117
## Common Patterns
118

119
### Form Interaction
120

121
```javascript
122
// Fill and submit form
123
const name = screen.getByLabelText('Name');
124
const email = screen.getByLabelText('Email');
125
const checkbox = screen.getByLabelText('I agree');
126

127
fireEvent.change(name, {target: {value: 'John Doe'}});
128
fireEvent.change(email, {target: {value: 'john@example.com'}});
129
fireEvent.click(checkbox);
130
fireEvent.submit(screen.getByRole('form'));
131

132
// Verify submission
133
expect(screen.getByText('Thank you')).toBeInTheDocument();
134
```
135

136
### Keyboard Navigation
137

138
```javascript
139
const listbox = screen.getByRole('listbox');
140

141
// Navigate with keyboard
142
fireEvent.keyDown(listbox, {key: 'ArrowDown'});
143
fireEvent.keyDown(listbox, {key: 'ArrowDown'});
144
fireEvent.keyDown(listbox, {key: 'Enter'});
145
```
146

147
### Drag and Drop
148

149
```javascript
150
const draggable = screen.getByTestId('draggable-item');
151
const dropZone = screen.getByTestId('drop-zone');
152

153
fireEvent.dragStart(draggable);
154
fireEvent.dragEnter(dropZone);
155
fireEvent.dragOver(dropZone);
156
fireEvent.drop(dropZone);
157
fireEvent.dragEnd(draggable);
158
```
159

160
## Event Properties
161

162
You can pass event properties through the options parameter:
163

164
```javascript
165
// Mouse with coordinates
166
fireEvent.mouseDown(element, {clientX: 100, clientY: 100});
167

168
// Keyboard modifiers
169
fireEvent.keyDown(element, {
170
  key: 'A',
171
  keyCode: 65,
172
  ctrlKey: true
173
});
174

175
// Custom properties
176
fireEvent.click(button, {
177
  button: 0,  // Left click
178
  bubbles: true,
179
  cancelable: true
180
});
181
```
182

183
## createEvent
184

185
Create event objects without firing them (for advanced use cases).
186

187
```typescript
188
const createEvent: CreateFunction & CreateObject;
189

190
type CreateFunction = (
191
  eventName: string,
192
  node: Node | Document | Window,
193
  init?: {},
194
  options?: {EventType?: string; defaultInit?: {}}
195
) => Event;
196
```
197

198
Example:
199
```javascript
200
const event = createEvent.click(element, {
201
  bubbles: true,
202
  cancelable: true,
203
  button: 0
204
});
205

206
element.dispatchEvent(event);
207
// Or
208
fireEvent(element, event);
209
```
210

211
## Note on User Event Library
212

213
For more realistic user interactions, consider `@testing-library/user-event` which simulates complete user sequences (e.g., mousedown → mouseup → click).
214

215
```javascript
216
// fireEvent - single event
217
fireEvent.click(button);
218

219
// user-event - full sequence
220
import userEvent from '@testing-library/user-event';
221
await userEvent.click(button);  // Fires mousedown, mouseup, click
222
```
223

224