0
# User Input & Actions
1

2
Mouse interactions, keyboard input, touch gestures, and complex user actions for comprehensive browser automation.
3

4
## Capabilities
5

6
### Mouse Actions
7

8
Perform mouse clicks, movements, and button operations.
9

10
```javascript { .api }
11
/**
12
 * Click mouse button at current location
13
 * @param button - Mouse button (0=left, 1=middle, 2=right)
14
 * @param cb - Callback receiving (err)
15
 */
16
click(button?: number, cb?: callback): void;
17

18
/**
19
 * Double-click at current mouse location
20
 * @param cb - Callback receiving (err)
21
 */
22
doubleclick(cb?: callback): void;
23

24
/**
25
 * Press mouse button down
26
 * @param button - Mouse button (0=left, 1=middle, 2=right)
27
 * @param cb - Callback receiving (err)
28
 */
29
buttonDown(button?: number, cb?: callback): void;
30

31
/**
32
 * Release mouse button
33
 * @param button - Mouse button (0=left, 1=middle, 2=right)
34
 * @param cb - Callback receiving (err)
35
 */
36
buttonUp(button?: number, cb?: callback): void;
37

38
/**
39
 * Move mouse to element or coordinates
40
 * @param element - Target element (optional)
41
 * @param xOffset - X offset from element center
42
 * @param yOffset - Y offset from element center
43
 * @param cb - Callback receiving (err)
44
 */
45
moveTo(element?: Element, xOffset?: number, yOffset?: number, cb?: callback): void;
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
// Basic mouse operations
52
browser.click(function(err) {
53
  if (err) throw err;
54
  console.log('Left click performed');
55
});
56

57
// Right-click context menu
58
browser.click(2, function(err) {
59
  console.log('Right-click performed');
60
});
61

62
// Move to element and click
63
browser.elementById('target-button', function(err, element) {
64
  browser.moveTo(element, function(err) {
65
    browser.click();
66
  });
67
});
68

69
// Promise chain style mouse operations
70
browser
71
  .elementByCss('.draggable')
72
  .moveTo()
73
  .buttonDown(0)        // Press left button
74
  .moveTo(null, 100, 50) // Move 100px right, 50px down
75
  .buttonUp(0);         // Release left button
76
```
77

78
### Keyboard Input
79

80
Send keyboard input and special keys.
81

82
```javascript { .api }
83
/**
84
 * Send keys to currently focused element or browser
85
 * @param keys - String or array of keys to send
86
 * @param cb - Callback receiving (err)
87
 */
88
keys(keys: string | string[], cb?: callback): void;
89

90
/**
91
 * Type text into specific element
92
 * @param element - Target element
93
 * @param keys - Text or keys to type
94
 * @param cb - Callback receiving (err)
95
 */
96
type(element: Element, keys: string | string[], cb?: callback): void;
97

98
/**
99
 * Replace element text content
100
 * @param element - Target element
101
 * @param keys - New text content
102
 * @param cb - Callback receiving (err)
103
 */
104
replace(element: Element, keys: string | string[], cb?: callback): void;
105

106
/**
107
 * Clear element text content
108
 * @param element - Target element
109
 * @param cb - Callback receiving (err)
110
 */
111
clear(element: Element, cb?: callback): void;
112
```
113

114
**Usage Examples:**
115

116
```javascript
117
const wd = require('wd');
118

119
// Type into form fields
120
browser.elementById('username', function(err, usernameField) {
121
  browser.type(usernameField, 'testuser@example.com');
122
});
123

124
browser.elementById('password', function(err, passwordField) {
125
  browser.type(passwordField, 'secretpassword');
126
});
127

128
// Send special keys
129
browser.keys([wd.SPECIAL_KEYS.Tab, wd.SPECIAL_KEYS.Enter]);
130

131
// Clear and replace text
132
browser.elementById('search-input', function(err, searchField) {
133
  browser.clear(searchField);
134
  browser.type(searchField, 'new search term');
135
});
136

137
// Promise chain keyboard input
138
browser
139
  .elementById('comment-box')
140
  .clear()
141
  .type('This is my comment')
142
  .keys([wd.SPECIAL_KEYS.Shift, wd.SPECIAL_KEYS.Tab]) // Shift+Tab
143
  .keys(wd.SPECIAL_KEYS.Enter);
144
```
145

146
### Element Interactions
147

148
Direct element interaction methods.
149

150
```javascript { .api }
151
/**
152
 * Click on specific element
153
 * @param element - Element to click
154
 * @param cb - Callback receiving (err)
155
 */
156
clickElement(element: Element, cb?: callback): void;
157

158
/**
159
 * Submit form containing the element
160
 * @param element - Form element or element within form
161
 * @param cb - Callback receiving (err)
162
 */
163
submit(element: Element, cb?: callback): void;
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
// Click specific elements
170
browser.elementById('login-button', function(err, button) {
171
  browser.clickElement(button);
172
});
173

174
// Submit forms
175
browser.elementById('login-form', function(err, form) {
176
  browser.submit(form);
177
});
178

179
// Or submit via any form element
180
browser.elementById('username', function(err, input) {
181
  browser.type(input, 'user@example.com');
182
  browser.submit(input); // Submits the containing form
183
});
184
```
185

186
### Touch and Mobile Actions
187

188
Touch gestures and mobile-specific interactions.
189

190
```javascript { .api }
191
/**
192
 * Tap element (mobile/touch)
193
 * @param element - Element to tap
194
 * @param cb - Callback receiving (err)
195
 */
196
tapElement(element: Element, cb?: callback): void;
197

198
/**
199
 * Flick gesture on element
200
 * @param element - Target element
201
 * @param xSpeed - Horizontal flick speed
202
 * @param ySpeed - Vertical flick speed
203
 * @param cb - Callback receiving (err)
204
 */
205
flick(element: Element, xSpeed: number, ySpeed: number, cb?: callback): void;
206

207
/**
208
 * Scroll by offset
209
 * @param xOffset - Horizontal scroll offset
210
 * @param yOffset - Vertical scroll offset
211
 * @param cb - Callback receiving (err)
212
 */
213
scroll(xOffset: number, yOffset: number, cb?: callback): void;
214
```
215

216
**Usage Examples:**
217

218
```javascript
219
// Mobile touch interactions
220
browser.elementByCss('.mobile-button', function(err, button) {
221
  browser.tapElement(button);
222
});
223

224
// Flick gestures for scrolling
225
browser.elementByCss('.scrollable-area', function(err, area) {
226
  browser.flick(area, 0, -100); // Flick up to scroll down
227
});
228

229
// Page scrolling
230
browser.scroll(0, 300); // Scroll down 300 pixels
231
```
232

233
### Special Keys Reference
234

235
Access special keyboard keys for complex input scenarios.
236

237
```javascript { .api }
238
// Special keys available in wd.SPECIAL_KEYS
239
const SPECIAL_KEYS: {
240
  NULL: string;
241
  Tab: string;
242
  Enter: string;
243
  Return: string;
244
  Shift: string;
245
  Control: string;
246
  Alt: string;
247
  Pause: string;
248
  Escape: string;
249
  Space: string;
250
  Pageup: string;
251
  Pagedown: string;
252
  End: string;
253
  Home: string;
254
  'Left arrow': string;
255
  'Up arrow': string;
256
  'Right arrow': string;
257
  'Down arrow': string;
258
  Insert: string;
259
  Delete: string;
260
  'Back space': string;
261
  Clear: string;
262
  Help: string;
263
  Cancel: string;
264
  // Function keys F1-F12
265
  F1: string;
266
  F2: string;
267
  // ... F3 through F12
268
  // Numpad keys
269
  'Numpad 0': string;
270
  'Numpad 1': string;
271
  // ... through Numpad 9
272
  Multiply: string;
273
  Add: string;
274
  Subtract: string;
275
  Decimal: string;
276
  Divide: string;
277
  Semicolon: string;
278
  Equals: string;
279
  Command: string;
280
  Meta: string;
281
};
282
```
283

284
**Usage Examples:**
285

286
```javascript
287
const wd = require('wd');
288

289
// Use special keys for navigation
290
browser.keys([
291
  wd.SPECIAL_KEYS.Control,
292
  'a'  // Ctrl+A to select all
293
]);
294

295
browser.keys(wd.SPECIAL_KEYS.Delete); // Delete selected text
296

297
// Form navigation
298
browser.keys([
299
  wd.SPECIAL_KEYS.Tab,        // Move to next field
300
  wd.SPECIAL_KEYS.Tab,        // Move to next field
301
  wd.SPECIAL_KEYS.Shift,      // Hold Shift
302
  wd.SPECIAL_KEYS.Tab         // Shift+Tab to go back
303
]);
304

305
// Function keys
306
browser.keys(wd.SPECIAL_KEYS.F5); // Refresh page
307
browser.keys(wd.SPECIAL_KEYS.F12); // Developer tools
308

309
// Arrow key navigation
310
browser.keys([
311
  wd.SPECIAL_KEYS['Down arrow'],
312
  wd.SPECIAL_KEYS['Down arrow'],
313
  wd.SPECIAL_KEYS.Enter
314
]);
315
```
316

317
### File Upload
318

319
Handle file uploads in web forms.
320

321
```javascript { .api }
322
/**
323
 * Upload file to file input element
324
 * @param filepath - Local path to file
325
 * @param cb - Callback receiving (err, remoteFilePath)
326
 */
327
uploadFile(filepath: string, cb?: callback): string;
328
```
329

330
**Usage Examples:**
331

332
```javascript
333
// Upload file through input element
334
browser.elementByCss('input[type="file"]', function(err, fileInput) {
335
  browser.uploadFile('/path/to/local/file.pdf', function(err, remotePath) {
336
    if (err) throw err;
337
    console.log('File uploaded to:', remotePath);
338
    
339
    // Set the file path to the input
340
    browser.type(fileInput, remotePath);
341
  });
342
});
343

344
// Promise chain file upload
345
browser
346
  .uploadFile('./test-files/document.pdf')
347
  .then(remotePath => {
348
    return browser.elementByCss('input[type="file"]');
349
  })
350
  .then(fileInput => {
351
    return browser.type(fileInput, remotePath);
352
  })
353
  .elementById('upload-button')
354
  .click();
355
```
356

357
### Advanced Input Combinations
358

359
Complex input scenarios combining multiple interaction types.
360

361
**Usage Examples:**
362

363
```javascript
364
// Complex form filling
365
browser
366
  .elementById('first-name')
367
  .clear()
368
  .type('John')
369
  .keys(wd.SPECIAL_KEYS.Tab)      // Move to next field
370
  .type('Doe')                     // Type into last name
371
  .keys(wd.SPECIAL_KEYS.Tab)      // Move to email field
372
  .type('john.doe@example.com')
373
  .elementById('country-select')   // Click dropdown
374
  .click()
375
  .keys(['U', 'n', 'i'])          // Type to filter options
376
  .keys(wd.SPECIAL_KEYS.Enter)    // Select option
377
  .elementById('submit-form')
378
  .click();
379

380
// Drag and drop simulation
381
browser
382
  .elementByCss('.draggable-item')
383
  .moveTo()
384
  .buttonDown(0)                   // Start drag
385
  .elementByCss('.drop-zone')
386
  .moveTo()
387
  .buttonUp(0);                    // End drag
388

389
// Multi-selection with Ctrl key
390
browser
391
  .elementByCss('.item-1')
392
  .click()
393
  .keys(wd.SPECIAL_KEYS.Control)   // Hold Ctrl
394
  .elementByCss('.item-3')
395
  .click()                         // Ctrl+click for multi-select
396
  .elementByCss('.item-5')
397
  .click();                        // Another Ctrl+click
398
```