0
# Input Simulation
1

2
Comprehensive input simulation including keyboard, mouse, and touch interactions for realistic user behavior testing and automation scenarios.
3

4
## Capabilities
5

6
### Keyboard Input
7

8
Simulate keyboard interactions including key presses, text typing, and keyboard shortcuts.
9

10
```typescript { .api }
11
/**
12
 * Keyboard input simulation interface
13
 */
14
interface Keyboard {
15
  /** Press key down (without releasing) */
16
  down(key: string, options?: KeyboardDownOptions): Promise<void>;
17
  /** Release key */
18
  up(key: string): Promise<void>;
19
  /** Press and release key */
20
  press(key: string, options?: KeyboardPressOptions): Promise<void>;
21
  /** Type text character by character */
22
  type(text: string, options?: KeyboardTypeOptions): Promise<void>;
23
  /** Insert text without simulating key events */
24
  insertText(text: string): Promise<void>;
25
}
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
// Access keyboard from page
32
const keyboard = page.keyboard;
33

34
// Basic key presses
35
await keyboard.press('Enter');
36
await keyboard.press('Tab');
37
await keyboard.press('Escape');
38

39
// Key combinations
40
await keyboard.down('Control');
41
await keyboard.press('a'); // Ctrl+A
42
await keyboard.up('Control');
43

44
// Modifier shortcuts
45
await keyboard.press('Control+c'); // Copy
46
await keyboard.press('Control+v'); // Paste
47
await keyboard.press('Control+Shift+Tab'); // Previous tab
48

49
// Type text with realistic delays
50
await keyboard.type('Hello World!', { delay: 100 });
51

52
// Insert text instantly
53
await keyboard.insertText('Bulk text insertion');
54

55
// Complex key sequences
56
await keyboard.down('Shift');
57
await keyboard.press('ArrowRight');
58
await keyboard.press('ArrowRight');
59
await keyboard.up('Shift'); // Select text
60
await keyboard.press('Delete');
61
```
62

63
### Mouse Input
64

65
Simulate mouse movements, clicks, drags, and scroll wheel interactions.
66

67
```typescript { .api }
68
/**
69
 * Mouse input simulation interface
70
 */
71
interface Mouse {
72
  /** Move mouse cursor to coordinates */
73
  move(x: number, y: number, options?: MouseMoveOptions): Promise<void>;
74
  /** Click at coordinates */
75
  click(x: number, y: number, options?: MouseClickOptions): Promise<void>;
76
  /** Double-click at coordinates */
77
  dblclick(x: number, y: number, options?: MouseDblclickOptions): Promise<void>;
78
  /** Press mouse button down */
79
  down(options?: MouseDownOptions): Promise<void>;
80
  /** Release mouse button */
81
  up(options?: MouseUpOptions): Promise<void>;
82
  /** Scroll mouse wheel */
83
  wheel(deltaX: number, deltaY: number): Promise<void>;
84
}
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
// Access mouse from page
91
const mouse = page.mouse;
92

93
// Basic mouse operations
94
await mouse.move(100, 200);
95
await mouse.click(100, 200);
96
await mouse.dblclick(100, 200);
97

98
// Drag and drop
99
await mouse.move(100, 100);
100
await mouse.down();
101
await mouse.move(200, 200);
102
await mouse.up();
103

104
// Right-click context menu
105
await mouse.click(150, 150, { button: 'right' });
106

107
// Mouse wheel scrolling
108
await mouse.wheel(0, -100); // Scroll up
109
await mouse.wheel(0, 100);  // Scroll down
110
await mouse.wheel(-50, 0);  // Scroll left
111
await mouse.wheel(50, 0);   // Scroll right
112

113
// Custom click options
114
await mouse.click(100, 100, {
115
  button: 'middle',
116
  clickCount: 2,
117
  delay: 100
118
});
119

120
// Hold mouse button
121
await mouse.down({ button: 'left' });
122
await page.waitForTimeout(1000);
123
await mouse.up({ button: 'left' });
124
```
125

126
### Touch Input
127

128
Simulate touch interactions for mobile and touch-enabled device testing.
129

130
```typescript { .api }
131
/**
132
 * Touch input simulation interface
133
 */
134
interface Touchscreen {
135
  /** Perform single tap gesture */
136
  tap(x: number, y: number): Promise<void>;
137
}
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
// Access touchscreen from page
144
const touch = page.touchscreen;
145

146
// Basic tap gesture
147
await touch.tap(100, 200);
148

149
// Multi-touch simulation (using evaluate)
150
await page.evaluate(() => {
151
  // Simulate pinch gesture
152
  const element = document.elementFromPoint(200, 200);
153
  if (element) {
154
    const touchStart = new TouchEvent('touchstart', {
155
      touches: [
156
        new Touch({ identifier: 1, target: element, clientX: 100, clientY: 100 }),
157
        new Touch({ identifier: 2, target: element, clientX: 200, clientY: 100 })
158
      ]
159
    });
160
    element.dispatchEvent(touchStart);
161
  }
162
});
163
```
164

165
### Page-Level Input Methods
166

167
High-level input methods that automatically target specific elements and handle focus.
168

169
```typescript { .api }
170
/**
171
 * Element-targeted input methods
172
 */
173
interface Page {
174
  /** Click element by selector */
175
  click(selector: string, options?: PageClickOptions): Promise<void>;
176
  /** Double-click element by selector */
177
  dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;
178
  /** Fill input element with text */
179
  fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;
180
  /** Type text into element */
181
  type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;
182
  /** Press key on element */
183
  press(selector: string, key: string, options?: PagePressOptions): Promise<void>;
184
  /** Check checkbox or radio button */
185
  check(selector: string, options?: PageCheckOptions): Promise<void>;
186
  /** Uncheck checkbox */
187
  uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;
188
  /** Select options from dropdown */
189
  selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;
190
  /** Hover over element */
191
  hover(selector: string, options?: PageHoverOptions): Promise<void>;
192
  /** Focus element */
193
  focus(selector: string, options?: PageFocusOptions): Promise<void>;
194
  /** Dispatch event on element */
195
  dispatchEvent(selector: string, type: string, eventInit?: any, options?: PageDispatchEventOptions): Promise<void>;
196
}
197
```
198

199
**Usage Examples:**
200

201
```typescript
202
// Element-specific interactions
203
await page.click('button#submit');
204
await page.fill('input[name="email"]', 'user@example.com');
205
await page.type('textarea', 'Some long text...', { delay: 50 });
206
await page.press('input[name="search"]', 'Enter');
207

208
// Form interactions
209
await page.check('input[type="checkbox"]');
210
await page.selectOption('select[name="country"]', 'USA');
211

212
// Hover and focus
213
await page.hover('.dropdown-trigger');
214
await page.focus('input[name="username"]');
215

216
// Custom events
217
await page.dispatchEvent('button', 'click', { 
218
  bubbles: true, 
219
  cancelable: true 
220
});
221

222
// Advanced click with modifiers
223
await page.click('a.link', {
224
  modifiers: ['Control'], // Ctrl+Click to open in new tab
225
  button: 'middle'        // Middle click
226
});
227
```
228

229
## Advanced Input Patterns
230

231
### Drag and Drop
232

233
```typescript
234
// Drag and drop using mouse
235
const source = await page.locator('#source').boundingBox();
236
const target = await page.locator('#target').boundingBox();
237

238
if (source && target) {
239
  await page.mouse.move(source.x + source.width / 2, source.y + source.height / 2);
240
  await page.mouse.down();
241
  await page.mouse.move(target.x + target.width / 2, target.y + target.height / 2);
242
  await page.mouse.up();
243
}
244

245
// Using HTML5 drag and drop API
246
await page.dragAndDrop('#source', '#target');
247
```
248

249
### File Upload
250

251
```typescript
252
// Upload single file
253
await page.setInputFiles('input[type="file"]', 'path/to/file.txt');
254

255
// Upload multiple files
256
await page.setInputFiles('input[type="file"]', [
257
  'path/to/file1.txt',
258
  'path/to/file2.txt'
259
]);
260

261
// Upload from buffer
262
await page.setInputFiles('input[type="file"]', {
263
  name: 'test.txt',
264
  mimeType: 'text/plain',
265
  buffer: Buffer.from('Hello World')
266
});
267
```
268

269
### Keyboard Shortcuts
270

271
```typescript
272
// Common shortcuts
273
await page.keyboard.press('Control+a'); // Select all
274
await page.keyboard.press('Control+c'); // Copy
275
await page.keyboard.press('Control+v'); // Paste
276
await page.keyboard.press('Control+z'); // Undo
277
await page.keyboard.press('Control+y'); // Redo
278

279
// Browser shortcuts
280
await page.keyboard.press('F5');           // Refresh
281
await page.keyboard.press('Control+F5');   // Hard refresh
282
await page.keyboard.press('Control+t');    // New tab
283
await page.keyboard.press('Control+w');    // Close tab
284

285
// Text editing shortcuts
286
await page.keyboard.press('Home');         // Start of line
287
await page.keyboard.press('End');          // End of line
288
await page.keyboard.press('Control+Home'); // Start of document
289
await page.keyboard.press('Control+End');  // End of document
290

291
// Selection shortcuts
292
await page.keyboard.press('Shift+ArrowRight'); // Select character
293
await page.keyboard.press('Control+Shift+ArrowRight'); // Select word
294
await page.keyboard.press('Shift+End'); // Select to end of line
295
```
296

297
## Configuration Types
298

299
### Keyboard Options
300

301
```typescript { .api }
302
interface KeyboardDownOptions {
303
  /** Whether to generate a keydown event */
304
  keydown?: boolean;
305
}
306

307
interface KeyboardPressOptions {
308
  /** Time to wait between keydown and keyup */
309
  delay?: number;
310
}
311

312
interface KeyboardTypeOptions {
313
  /** Time to wait between key presses */
314
  delay?: number;
315
}
316
```
317

318
### Mouse Options
319

320
```typescript { .api }
321
interface MouseMoveOptions {
322
  /** Number of intermediate mousemove events */
323
  steps?: number;
324
}
325

326
interface MouseClickOptions {
327
  /** Which button to click */
328
  button?: 'left' | 'right' | 'middle';
329
  /** Number of clicks */
330
  clickCount?: number;
331
  /** Time to wait between mousedown and mouseup */
332
  delay?: number;
333
}
334

335
interface MouseDblclickOptions {
336
  /** Which button to double-click */
337
  button?: 'left' | 'right' | 'middle';
338
  /** Time to wait between clicks */
339
  delay?: number;
340
}
341

342
interface MouseDownOptions {
343
  /** Which button to press */
344
  button?: 'left' | 'right' | 'middle';
345
  /** Number of clicks */
346
  clickCount?: number;
347
}
348

349
interface MouseUpOptions {
350
  /** Which button to release */
351
  button?: 'left' | 'right' | 'middle';
352
  /** Number of clicks */
353
  clickCount?: number;
354
}
355
```
356

357
### Page Input Options
358

359
```typescript { .api }
360
interface PageClickOptions {
361
  /** Which button to click */
362
  button?: 'left' | 'right' | 'middle';
363
  /** Number of clicks */
364
  clickCount?: number;
365
  /** Delay between mousedown and mouseup */
366
  delay?: number;
367
  /** Position relative to element */
368
  position?: { x: number; y: number; };
369
  /** Modifier keys to hold */
370
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
371
  /** Bypass actionability checks */
372
  force?: boolean;
373
  /** No action, just perform checks */
374
  trial?: boolean;
375
  /** Wait timeout */
376
  timeout?: number;
377
}
378

379
interface PageFillOptions {
380
  /** Bypass actionability checks */
381
  force?: boolean;
382
  /** No action, just perform checks */
383
  trial?: boolean;
384
  /** Wait timeout */
385
  timeout?: number;
386
}
387

388
interface PageTypeOptions {
389
  /** Delay between key presses */
390
  delay?: number;
391
  /** Wait timeout */
392
  timeout?: number;
393
}
394

395
interface PageHoverOptions {
396
  /** Position relative to element */
397
  position?: { x: number; y: number; };
398
  /** Modifier keys to hold */
399
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
400
  /** Bypass actionability checks */
401
  force?: boolean;
402
  /** No action, just perform checks */
403
  trial?: boolean;
404
  /** Wait timeout */
405
  timeout?: number;
406
}
407
```
408

409
## Key Constants
410

411
### Special Keys
412

413
```typescript { .api }
414
type SpecialKey = 
415
  | 'Backspace' | 'Tab' | 'Enter' | 'Shift' | 'Control' | 'Alt' | 'Pause'
416
  | 'CapsLock' | 'Escape' | 'Space' | 'PageUp' | 'PageDown' | 'End' | 'Home'
417
  | 'ArrowLeft' | 'ArrowUp' | 'ArrowRight' | 'ArrowDown' | 'Insert' | 'Delete'
418
  | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12'
419
  | 'NumLock' | 'ScrollLock' | 'Meta' | 'ContextMenu';
420
```
421

422
### Modifier Keys
423

424
```typescript { .api }
425
type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift';
426

427
// Platform-specific aliases
428
// On macOS: 'Meta' = Command key, 'Control' = Control key
429
// On Windows/Linux: 'Meta' = Windows key, 'Control' = Control key
430
```
431

432
**Usage Examples:**
433

434
```typescript
435
// Function keys
436
await page.keyboard.press('F12'); // Open dev tools
437

438
// Navigation keys
439
await page.keyboard.press('Home');
440
await page.keyboard.press('End');
441
await page.keyboard.press('PageDown');
442

443
// Modifier combinations
444
await page.keyboard.press('Control+Shift+I'); // Open dev tools
445
await page.keyboard.press('Alt+Tab'); // Switch applications
446

447
// Text manipulation
448
await page.keyboard.press('Control+a'); // Select all
449
await page.keyboard.press('Delete'); // Delete selection
450
```