0
# Element Interaction
1

2
Complete element interaction capabilities including clicks, input, drag-and-drop, touch gestures, state checking, and element properties.
3

4
## Capabilities
5

6
### Mouse Interactions
7

8
Methods for simulating mouse interactions with elements.
9

10
```typescript { .api }
11
/**
12
 * Click on an element
13
 * @param options - Click options including button type and coordinates
14
 * @returns Promise that resolves when click is complete
15
 */
16
click(options?: ClickOptions): Promise<void>;
17

18
/**
19
 * Double-click on an element
20
 * @returns Promise that resolves when double-click is complete
21
 */
22
doubleClick(): Promise<void>;
23

24
/**
25
 * Move mouse cursor to an element
26
 * @param options - Movement options with optional offset coordinates
27
 * @returns Promise that resolves when movement is complete
28
 */
29
moveTo(options?: {xOffset?: number, yOffset?: number}): Promise<void>;
30

31
interface ClickOptions {
32
  button: 'left' | 'middle' | 'right' | number;
33
  x: number;
34
  y: number;
35
  duration: number;
36
  skipRelease: boolean;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
const button = await browser.$('#submit-btn');
44

45
// Basic click
46
await button.click();
47

48
// Right-click
49
await button.click({ button: 'right' });
50

51
// Click with offset
52
await button.click({ x: 10, y: 5 });
53

54
// Double-click
55
await button.doubleClick();
56

57
// Move to element
58
await button.moveTo();
59
await button.moveTo({ xOffset: 20, yOffset: 10 });
60
```
61

62
### Drag and Drop
63

64
Drag and drop functionality for moving elements or performing complex gestures.
65

66
```typescript { .api }
67
/**
68
 * Drag this element and drop it on another element or coordinate
69
 * @param target - Target element or coordinates to drop on
70
 * @returns Promise that resolves when drag and drop is complete
71
 */
72
dragAndDrop(target: WebdriverIO.Element | {x: number, y: number}): Promise<void>;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
const source = await browser.$('#draggable-item');
79
const target = await browser.$('#drop-zone');
80

81
// Drag to another element
82
await source.dragAndDrop(target);
83

84
// Drag to specific coordinates
85
await source.dragAndDrop({ x: 100, y: 200 });
86
```
87

88
### Input and Text Entry
89

90
Methods for entering text and managing input field values.
91

92
```typescript { .api }
93
/**
94
 * Set the value of an input element, clearing any existing value
95
 * @param value - Value to set in the input field
96
 * @returns Promise that resolves when value is set
97
 */
98
setValue(value: string | number): Promise<void>;
99

100
/**
101
 * Add value to an input element without clearing existing value
102
 * @param value - Value to append to the input field
103
 * @returns Promise that resolves when value is added
104
 */
105
addValue(value: string | number): Promise<void>;
106

107
/**
108
 * Clear the value of an input element
109
 * @returns Promise that resolves when value is cleared
110
 */
111
clearValue(): Promise<void>;
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
const emailInput = await browser.$('#email');
118
const passwordInput = await browser.$('#password');
119

120
// Set complete value (clears existing)
121
await emailInput.setValue('user@example.com');
122
await passwordInput.setValue('secretpassword');
123

124
// Add to existing value
125
await emailInput.addValue('+work');
126

127
// Clear input
128
await emailInput.clearValue();
129
```
130

131
### Element State Checking
132

133
Methods for checking various states and properties of elements.
134

135
```typescript { .api }
136
/**
137
 * Check if element exists in the DOM
138
 * @returns Promise resolving to boolean indicating existence
139
 */
140
isExisting(): Promise<boolean>;
141

142
/**
143
 * Check if element is displayed (visible)
144
 * @returns Promise resolving to boolean indicating visibility
145
 */
146
isDisplayed(): Promise<boolean>;
147

148
/**
149
 * Check if element is enabled for interaction
150
 * @returns Promise resolving to boolean indicating enabled state
151
 */
152
isEnabled(): Promise<boolean>;
153

154
/**
155
 * Check if element is selected (checkboxes, radio buttons, options)
156
 * @returns Promise resolving to boolean indicating selected state
157
 */
158
isSelected(): Promise<boolean>;
159

160
/**
161
 * Check if element currently has focus
162
 * @returns Promise resolving to boolean indicating focus state
163
 */
164
isFocused(): Promise<boolean>;
165

166
/**
167
 * Check if element is clickable (visible, enabled, not obscured)
168
 * @returns Promise resolving to boolean indicating clickable state
169
 */
170
isClickable(): Promise<boolean>;
171

172
/**
173
 * Check if element is stable (not moving or changing)
174
 * @returns Promise resolving to boolean indicating stability
175
 */
176
isStable(): Promise<boolean>;
177

178
/**
179
 * Check if this element is equal to another element
180
 * @param element - Element to compare with
181
 * @returns Promise resolving to boolean indicating equality
182
 */
183
isEqual(element: WebdriverIO.Element): Promise<boolean>;
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
const button = await browser.$('#submit-btn');
190
const checkbox = await browser.$('#agree-terms');
191

192
// Check various states
193
const exists = await button.isExisting();
194
const visible = await button.isDisplayed();
195
const enabled = await button.isEnabled();
196
const clickable = await button.isClickable();
197

198
// Check form element states
199
const checked = await checkbox.isSelected();
200
const focused = await checkbox.isFocused();
201

202
// Compare elements
203
const anotherButton = await browser.$('#cancel-btn');
204
const same = await button.isEqual(anotherButton);
205
```
206

207
### Element Properties and Attributes
208

209
Methods for retrieving element properties, attributes, and content.
210

211
```typescript { .api }
212
/**
213
 * Get the visible text content of the element
214
 * @returns Promise resolving to the element's text content
215
 */
216
getText(): Promise<string>;
217

218
/**
219
 * Get the value of an input element
220
 * @returns Promise resolving to the element's value
221
 */
222
getValue(): Promise<string>;
223

224
/**
225
 * Get the value of an element attribute
226
 * @param attributeName - Name of the attribute to retrieve
227
 * @returns Promise resolving to the attribute value or null
228
 */
229
getAttribute(attributeName: string): Promise<string | null>;
230

231
/**
232
 * Get the value of an element property
233
 * @param propertyName - Name of the property to retrieve
234
 * @returns Promise resolving to the property value
235
 */
236
getProperty(propertyName: string): Promise<any>;
237

238
/**
239
 * Get the computed CSS property value
240
 * @param cssProperty - Name of the CSS property to retrieve
241
 * @returns Promise resolving to CSS property object
242
 */
243
getCSSProperty(cssProperty: string): Promise<object>;
244

245
/**
246
 * Get the HTML content of the element
247
 * @param includeSelectorTag - Whether to include the element's own tag
248
 * @returns Promise resolving to the HTML content
249
 */
250
getHTML(includeSelectorTag?: boolean): Promise<string>;
251

252
/**
253
 * Get the tag name of the element
254
 * @returns Promise resolving to the element's tag name
255
 */
256
getTagName(): Promise<string>;
257

258
/**
259
 * Get the size dimensions of the element
260
 * @returns Promise resolving to object with width and height
261
 */
262
getSize(): Promise<{width: number, height: number}>;
263

264
/**
265
 * Get the location coordinates of the element
266
 * @returns Promise resolving to object with x and y coordinates
267
 */
268
getLocation(): Promise<{x: number, y: number}>;
269

270
/**
271
 * Get the computed ARIA role of the element
272
 * @returns Promise resolving to the computed role
273
 */
274
getComputedRole(): Promise<string>;
275

276
/**
277
 * Get the computed ARIA label of the element
278
 * @returns Promise resolving to the computed label
279
 */
280
getComputedLabel(): Promise<string>;
281
```
282

283
**Usage Examples:**
284

285
```typescript
286
const element = await browser.$('#my-element');
287

288
// Get text and value
289
const text = await element.getText();
290
const value = await element.getValue();
291

292
// Get attributes and properties
293
const id = await element.getAttribute('id');
294
const className = await element.getAttribute('class');
295
const disabled = await element.getProperty('disabled');
296

297
// Get CSS properties
298
const color = await element.getCSSProperty('color');
299
const fontSize = await element.getCSSProperty('font-size');
300

301
// Get HTML and tag information
302
const html = await element.getHTML();
303
const htmlWithTag = await element.getHTML(true);
304
const tagName = await element.getTagName();
305

306
// Get dimensions and position
307
const size = await element.getSize();
308
const location = await element.getLocation();
309

310
// Get accessibility information
311
const role = await element.getComputedRole();
312
const label = await element.getComputedLabel();
313
```
314

315
### Select Element Operations
316

317
Specialized methods for interacting with HTML select elements.
318

319
```typescript { .api }
320
/**
321
 * Select option by its index position
322
 * @param index - Zero-based index of the option to select
323
 * @returns Promise that resolves when selection is complete
324
 */
325
selectByIndex(index: number): Promise<void>;
326

327
/**
328
 * Select option by attribute value
329
 * @param attribute - Attribute name to match against
330
 * @param value - Value of the attribute to select
331
 * @returns Promise that resolves when selection is complete
332
 */
333
selectByAttribute(attribute: string, value: string): Promise<void>;
334

335
/**
336
 * Select option by its visible text content
337
 * @param text - Visible text of the option to select
338
 * @returns Promise that resolves when selection is complete
339
 */
340
selectByVisibleText(text: string): Promise<void>;
341
```
342

343
**Usage Examples:**
344

345
```typescript
346
const selectElement = await browser.$('#country-select');
347

348
// Select by index (first option = 0)
349
await selectElement.selectByIndex(2);
350

351
// Select by attribute value
352
await selectElement.selectByAttribute('value', 'US');
353

354
// Select by visible text
355
await selectElement.selectByVisibleText('United States');
356
```
357

358
### Touch Interactions
359

360
Touch-based interactions for mobile and touch-enabled devices.
361

362
```typescript { .api }
363
/**
364
 * Perform touch action on the element
365
 * @param action - Touch action configuration object
366
 * @returns Promise that resolves when touch action is complete
367
 */
368
touchAction(action: object): Promise<void>;
369
```
370

371
**Usage Examples:**
372

373
```typescript
374
const element = await browser.$('#touch-target');
375

376
// Single tap
377
await element.touchAction('tap');
378

379
// Long press
380
await element.touchAction({
381
  action: 'longPress',
382
  duration: 1000
383
});
384

385
// Complex touch sequence
386
await element.touchAction([
387
  { action: 'press' },
388
  { action: 'wait', duration: 500 },
389
  { action: 'moveTo', x: 100, y: 0 },
390
  { action: 'release' }
391
]);
392
```
393

394
### Element Wait Methods
395

396
Critical wait methods for robust test automation, allowing tests to wait for elements to reach specific states.
397

398
```typescript { .api }
399
/**
400
 * Wait for element to be displayed (visible in the viewport)
401
 * @param options - Wait options including timeout and reverse condition
402
 * @returns Promise resolving to true when element is displayed
403
 */
404
waitForDisplayed(options?: {
405
  timeout?: number;
406
  reverse?: boolean;
407
  timeoutMsg?: string;
408
  interval?: number;
409
}): Promise<boolean>;
410

411
/**
412
 * Wait for element to be enabled (not disabled)
413
 * @param options - Wait options including timeout and reverse condition
414
 * @returns Promise resolving to true when element is enabled
415
 */
416
waitForEnabled(options?: {
417
  timeout?: number;
418
  reverse?: boolean;
419
  timeoutMsg?: string;
420
  interval?: number;
421
}): Promise<boolean>;
422

423
/**
424
 * Wait for element to exist in the DOM
425
 * @param options - Wait options including timeout and reverse condition
426
 * @returns Promise resolving to true when element exists
427
 */
428
waitForExist(options?: {
429
  timeout?: number;
430
  reverse?: boolean;
431
  timeoutMsg?: string;
432
  interval?: number;
433
}): Promise<boolean>;
434

435
/**
436
 * Wait for element to be clickable (visible, enabled, and not overlapped)
437
 * @param options - Wait options including timeout and reverse condition
438
 * @returns Promise resolving to true when element is clickable
439
 */
440
waitForClickable(options?: {
441
  timeout?: number;
442
  reverse?: boolean;
443
  timeoutMsg?: string;
444
  interval?: number;
445
}): Promise<boolean>;
446

447
/**
448
 * Wait for element to be stable (not moving or changing)
449
 * @param options - Wait options including timeout
450
 * @returns Promise resolving to true when element is stable
451
 */
452
waitForStable(options?: {
453
  timeout?: number;
454
  timeoutMsg?: string;
455
  interval?: number;
456
}): Promise<boolean>;
457
```
458

459
**Usage Examples:**
460

461
```typescript
462
const element = await browser.$('#dynamic-content');
463

464
// Wait for element to be displayed
465
await element.waitForDisplayed({ timeout: 5000 });
466

467
// Wait for element to disappear
468
await element.waitForDisplayed({ 
469
  reverse: true, 
470
  timeoutMsg: 'Element should have disappeared' 
471
});
472

473
// Wait for button to be clickable
474
const submitBtn = await browser.$('#submit');
475
await submitBtn.waitForClickable();
476
await submitBtn.click();
477

478
// Wait for element to exist in DOM
479
await element.waitForExist({ timeout: 10000 });
480

481
// Wait for form field to be enabled
482
const inputField = await browser.$('#user-input');
483
await inputField.waitForEnabled();
484
await inputField.setValue('test data');
485

486
// Wait for element to stop moving/changing
487
const animatedElement = await browser.$('#animation');
488
await animatedElement.waitForStable();
489
```
490

491
### Element Manipulation
492

493
Advanced element manipulation and interaction methods.
494

495
```typescript { .api }
496
/**
497
 * Scroll the element into the viewport
498
 * @param options - Scroll behavior options
499
 * @returns Promise that resolves when scrolling is complete
500
 */
501
scrollIntoView(options?: object): Promise<void>;
502

503
/**
504
 * Take a screenshot of just this element
505
 * @param filename - Path where screenshot should be saved
506
 * @returns Promise that resolves when screenshot is saved
507
 */
508
saveScreenshot(filename: string): Promise<void>;
509

510
/**
511
 * Execute JavaScript code with this element as context
512
 * @param script - JavaScript code or function to execute
513
 * @param args - Additional arguments to pass to the script
514
 * @returns Promise resolving to the script's return value
515
 */
516
execute(script: string | Function, ...args: any[]): Promise<any>;
517

518
/**
519
 * Execute asynchronous JavaScript code with this element as context
520
 * @param script - Async JavaScript code or function to execute
521
 * @param args - Additional arguments to pass to the script
522
 * @returns Promise resolving to the script's return value
523
 */
524
executeAsync(script: string | Function, ...args: any[]): Promise<any>;
525
```
526

527
**Usage Examples:**
528

529
```typescript
530
const element = await browser.$('#my-element');
531

532
// Scroll element into view
533
await element.scrollIntoView();
534
await element.scrollIntoView({ behavior: 'smooth', block: 'center' });
535

536
// Take element screenshot
537
await element.saveScreenshot('./element-screenshot.png');
538

539
// Execute JavaScript on element
540
const backgroundColor = await element.execute(function() {
541
  return this.style.backgroundColor;
542
});
543

544
// Execute async JavaScript
545
const result = await element.executeAsync(function(done) {
546
  setTimeout(() => {
547
    done(this.getBoundingClientRect());
548
  }, 100);
549
});
550
```