0
# Event Simulation
1

2
Vue-specific event firing utilities that properly handle Vue's asynchronous DOM updates and form interactions.
3

4
## Capabilities
5

6
### FireEvent Object
7

8
Main event firing utility that automatically waits for Vue's DOM updates after triggering events.
9

10
```typescript { .api }
11
/**
12
 * Fire DOM events on elements with Vue-specific async handling
13
 * @param element - Target element
14
 * @param event - Event object to fire
15
 * @returns Promise that resolves after Vue DOM updates
16
 */
17
declare const fireEvent: {
18
  (element: Element, event: Event): Promise<void>;
19
  
20
  /** Click event */
21
  click(element: Element, options?: MouseEventInit): Promise<void>;
22
  
23
  /** Double click event */
24
  dblClick(element: Element, options?: MouseEventInit): Promise<void>;
25
  
26
  /** Mouse down event */
27
  mouseDown(element: Element, options?: MouseEventInit): Promise<void>;
28
  
29
  /** Mouse up event */
30
  mouseUp(element: Element, options?: MouseEventInit): Promise<void>;
31
  
32
  /** Mouse enter event */
33
  mouseEnter(element: Element, options?: MouseEventInit): Promise<void>;
34
  
35
  /** Mouse leave event */
36
  mouseLeave(element: Element, options?: MouseEventInit): Promise<void>;
37
  
38
  /** Mouse move event */
39
  mouseMove(element: Element, options?: MouseEventInit): Promise<void>;
40
  
41
  /** Mouse over event */
42
  mouseOver(element: Element, options?: MouseEventInit): Promise<void>;
43
  
44
  /** Mouse out event */
45
  mouseOut(element: Element, options?: MouseEventInit): Promise<void>;
46
  
47
  /** Change event */
48
  change(element: Element, options?: EventInit): Promise<void>;
49
  
50
  /** Input event */
51
  input(element: Element, options?: InputEventInit): Promise<void>;
52
  
53
  /** Focus event */
54
  focus(element: Element, options?: FocusEventInit): Promise<void>;
55
  
56
  /** Blur event */
57
  blur(element: Element, options?: FocusEventInit): Promise<void>;
58
  
59
  /** Key down event */
60
  keyDown(element: Element, options?: KeyboardEventInit): Promise<void>;
61
  
62
  /** Key up event */
63
  keyUp(element: Element, options?: KeyboardEventInit): Promise<void>;
64
  
65
  /** Key press event */
66
  keyPress(element: Element, options?: KeyboardEventInit): Promise<void>;
67
  
68
  /** Submit event */
69
  submit(element: Element, options?: EventInit): Promise<void>;
70
  
71
  /** Load event */
72
  load(element: Element, options?: EventInit): Promise<void>;
73
  
74
  /** Error event */
75
  error(element: Element, options?: EventInit): Promise<void>;
76
  
77
  /** Scroll event */
78
  scroll(element: Element, options?: EventInit): Promise<void>;
79
  
80
  /** Resize event */
81
  resize(element: Element, options?: UIEventInit): Promise<void>;
82
  
83
  /** Vue-specific touch event (focus then blur) */
84
  touch(element: Element): Promise<void>;
85
  
86
  /** Vue-specific form update utility */
87
  update(element: Element, value?: string): Promise<void>;
88
};
89
```
90

91
**Usage Examples:**
92

93
```typescript
94
import { render, screen, fireEvent } from "@testing-library/vue";
95
import Counter from "./Counter.vue";
96

97
render(Counter);
98

99
// Basic click event
100
const button = screen.getByRole("button", { name: "Increment" });
101
await fireEvent.click(button);
102

103
// Input with keyboard events
104
const input = screen.getByLabelText("Search");
105
await fireEvent.focus(input);
106
await fireEvent.keyDown(input, { key: "A", code: "KeyA" });
107
await fireEvent.input(input, { target: { value: "Hello" } });
108

109
// Form submission
110
const form = screen.getByRole("form");
111
await fireEvent.submit(form);
112
```
113

114
### Vue-Specific Event Methods
115

116
#### Touch Event
117

118
Convenience method that focuses an element then immediately blurs it, useful for testing touch interactions.
119

120
```typescript { .api }
121
/**
122
 * Touch event - focus then blur an element
123
 * @param element - Element to touch
124
 * @returns Promise that resolves after both focus and blur complete
125
 */
126
function touch(element: Element): Promise<void>;
127
```
128

129
**Usage Example:**
130

131
```typescript
132
const touchButton = screen.getByRole("button");
133
await fireEvent.touch(touchButton);
134
```
135

136
#### Update Event
137

138
Special utility for handling Vue's v-model updates on form elements. Automatically determines the correct event type based on the element.
139

140
```typescript { .api }
141
/**
142
 * Update form element value (v-model helper)
143
 * @param element - Form element to update
144
 * @param value - New value (optional for checkboxes/radios)
145
 * @returns Promise that resolves after update completes
146
 */
147
function update(element: Element, value?: string): Promise<void>;
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
// Text input
154
const textInput = screen.getByLabelText("Name");
155
await fireEvent.update(textInput, "John Doe");
156

157
// Select dropdown
158
const select = screen.getByLabelText("Country");
159
await fireEvent.update(select, "USA");
160

161
// Checkbox (no value needed)
162
const checkbox = screen.getByRole("checkbox");
163
await fireEvent.update(checkbox);
164

165
// Radio button (no value needed)
166
const radio = screen.getByRole("radio", { name: "Option A" });
167
await fireEvent.update(radio);
168

169
// Select option
170
const option = screen.getByRole("option", { name: "Blue" });
171
await fireEvent.update(option);
172
```
173

174
### Event Options
175

176
#### Mouse Event Options
177

178
```typescript { .api }
179
interface MouseEventInit {
180
  /** Alt key pressed */
181
  altKey?: boolean;
182
  /** Mouse button pressed (0=left, 1=middle, 2=right) */
183
  button?: number;
184
  /** Buttons currently pressed */
185
  buttons?: number;
186
  /** X coordinate relative to client area */
187
  clientX?: number;
188
  /** Y coordinate relative to client area */
189
  clientY?: number;
190
  /** Ctrl key pressed */
191
  ctrlKey?: boolean;
192
  /** Meta key pressed */
193
  metaKey?: boolean;
194
  /** Related target element */
195
  relatedTarget?: Element | null;
196
  /** X coordinate relative to screen */
197
  screenX?: number;
198
  /** Y coordinate relative to screen */
199
  screenY?: number;
200
  /** Shift key pressed */
201
  shiftKey?: boolean;
202
}
203
```
204

205
#### Keyboard Event Options
206

207
```typescript { .api }
208
interface KeyboardEventInit {
209
  /** Alt key pressed */
210
  altKey?: boolean;
211
  /** Physical key code */
212
  code?: string;
213
  /** Ctrl key pressed */
214
  ctrlKey?: boolean;
215
  /** Logical key value */
216
  key?: string;
217
  /** Key location */
218
  location?: number;
219
  /** Meta key pressed */
220
  metaKey?: boolean;
221
  /** Key is auto-repeating */
222
  repeat?: boolean;
223
  /** Shift key pressed */
224
  shiftKey?: boolean;
225
}
226
```
227

228
#### Focus Event Options
229

230
```typescript { .api }
231
interface FocusEventInit {
232
  /** Related target element */
233
  relatedTarget?: Element | null;
234
}
235
```
236

237
#### Input Event Options
238

239
```typescript { .api }
240
interface InputEventInit {
241
  /** Input data */
242
  data?: string | null;
243
  /** Input type */
244
  inputType?: string;
245
  /** Is composing */
246
  isComposing?: boolean;
247
}
248
```
249

250
## Common Event Patterns
251

252
### Form Interactions
253

254
```typescript
255
// Fill out a form
256
const nameInput = screen.getByLabelText("Full Name");
257
const emailInput = screen.getByLabelText("Email");
258
const submitButton = screen.getByRole("button", { name: "Submit" });
259

260
await fireEvent.update(nameInput, "John Doe");
261
await fireEvent.update(emailInput, "john@example.com");
262
await fireEvent.click(submitButton);
263
```
264

265
### Keyboard Navigation
266

267
```typescript
268
// Navigate with keyboard
269
const input = screen.getByRole("textbox");
270
await fireEvent.focus(input);
271
await fireEvent.keyDown(input, { key: "Tab" });
272
await fireEvent.keyDown(document.activeElement, { key: "Enter" });
273
```
274

275
### Mouse Interactions
276

277
```typescript
278
// Hover and click
279
const button = screen.getByRole("button");
280
await fireEvent.mouseOver(button);
281
await fireEvent.mouseMove(button);
282
await fireEvent.click(button);
283
await fireEvent.mouseOut(button);
284
```
285

286
## Error Handling
287

288
Vue Testing Library will show warnings for potentially incorrect event usage:
289

290
- Using `fireEvent.change` or `fireEvent.input` directly may lead to unexpected results
291
- Recommended to use `fireEvent.update()` for form elements instead
292
- Warning can be disabled with `VTL_SKIP_WARN_EVENT_UPDATE` environment variable