0
# Element Interaction
1

2
Comprehensive element finding, interaction, and property access APIs for web element automation.
3

4
## Capabilities
5

6
### Element Discovery
7

8
Find single or multiple elements using various selector strategies.
9

10
```javascript { .api }
11
/**
12
 * Find single element by selector
13
 * @param selector - CSS selector or XPath
14
 * @returns Promise resolving with element
15
 */
16
browser.findElement(selector: string): Promise<WebElement>;
17

18
/**
19
 * Find multiple elements by selector
20
 * @param selector - CSS selector or XPath
21
 * @returns Promise resolving with array of elements
22
 */
23
browser.findElements(selector: string): Promise<WebElement[]>;
24

25
/**
26
 * Create element wrapper for chaining operations
27
 * @param selector - CSS selector or XPath
28
 * @returns Element wrapper instance
29
 */
30
browser.element(selector: string): Element;
31

32
/**
33
 * Create elements collection wrapper
34
 * @param selector - CSS selector or XPath
35
 * @returns Elements collection wrapper
36
 */
37
browser.elements(selector: string): Elements;
38

39
/**
40
 * Find child element by parent element ID
41
 * @param id - Parent element WebDriver ID
42
 * @param selector - Child element selector
43
 * @returns Promise resolving with child element
44
 */
45
browser.elementIdElement(id: string, selector: string): Promise<WebElement>;
46

47
/**
48
 * Find child elements by parent element ID
49
 * @param id - Parent element WebDriver ID
50
 * @param selector - Child elements selector
51
 * @returns Promise resolving with array of child elements
52
 */
53
browser.elementIdElements(id: string, selector: string): Promise<WebElement[]>;
54
```
55

56
**Usage Examples:**
57

58
```javascript
59
// Find single element
60
browser.findElement("#login-button").then(button => {
61
  console.log("Found login button");
62
});
63

64
// Find multiple elements
65
browser.findElements(".menu-item").then(items => {
66
  console.log(`Found ${items.length} menu items`);
67
});
68

69
// Use element wrapper
70
const loginForm = browser.element("#login-form");
71
```
72

73
### Element Interaction
74

75
Interact with elements through clicks, keyboard input, and form operations.
76

77
```javascript { .api }
78
/**
79
 * Click element at selector
80
 * @param selector - Element selector
81
 * @returns Promise resolving when click completes
82
 */
83
browser.click(selector: string);
84

85
/**
86
 * Double-click element
87
 * @param selector - Element selector
88
 * @returns Promise resolving when double-click completes
89
 */
90
browser.doubleClick(selector: string);
91

92
/**
93
 * Right-click element
94
 * @param selector - Element selector
95
 * @returns Promise resolving when right-click completes
96
 */
97
browser.rightClick(selector: string);
98

99
/**
100
 * Click and hold element
101
 * @param selector - Element selector
102
 * @returns Promise resolving when click-and-hold completes
103
 */
104
browser.clickAndHold(selector: string);
105

106
/**
107
 * Send keystrokes to element
108
 * @param selector - Element selector
109
 * @param keys - Keys to send
110
 * @returns Promise resolving when keys sent
111
 */
112
browser.sendKeys(selector: string, keys: string | string[]);
113

114
/**
115
 * Clear element input value
116
 * @param selector - Element selector
117
 * @returns Promise resolving when value cleared
118
 */
119
browser.clearValue(selector: string);
120

121
/**
122
 * Set element input value
123
 * @param selector - Element selector
124
 * @param value - Value to set
125
 * @returns Promise resolving when value set
126
 */
127
browser.setValue(selector: string, value: string);
128

129
/**
130
 * Update element value (clears then sets)
131
 * @param selector - Element selector
132
 * @param value - Value to update
133
 * @returns Promise resolving when value updated
134
 */
135
browser.updateValue(selector: string, value: string);
136

137
/**
138
 * Set password field value (secure input)
139
 * @param selector - Password field selector
140
 * @param password - Password to set
141
 * @returns Promise resolving when password set
142
 */
143
browser.setPassword(selector: string, password: string);
144

145
/**
146
 * Submit form containing element
147
 * @param selector - Form or form element selector
148
 * @returns Promise resolving when form submitted
149
 */
150
browser.submitForm(selector: string);
151

152
/**
153
 * Upload file to input element
154
 * @param selector - File input selector
155
 * @param filepath - Path to file to upload
156
 * @returns Promise resolving when file uploaded
157
 */
158
browser.uploadFile(selector: string, filepath: string);
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
// Basic interactions
165
browser.click("#submit-button");
166
browser.setValue("input[name='username']", "testuser");
167
browser.clearValue("input[name='search']");
168

169
// Form submission
170
browser.setValue("#username", "user");
171
browser.setValue("#password", "pass");
172
browser.submitForm("#login-form");
173

174
// File upload
175
browser.uploadFile("input[type='file']", "/path/to/document.pdf");
176
```
177

178
### Element State Queries
179

180
Check element state and visibility conditions.
181

182
```javascript { .api }
183
/**
184
 * Check if element is visible
185
 * @param selector - Element selector
186
 * @returns Promise resolving with visibility boolean
187
 */
188
browser.isVisible(selector: string): Promise<boolean>;
189

190
/**
191
 * Check if element exists in DOM
192
 * @param selector - Element selector
193
 * @returns Promise resolving with presence boolean
194
 */
195
browser.isPresent(selector: string): Promise<boolean>;
196

197
/**
198
 * Check if element is enabled for interaction
199
 * @param selector - Element selector
200
 * @returns Promise resolving with enabled boolean
201
 */
202
browser.isEnabled(selector: string): Promise<boolean>;
203

204
/**
205
 * Check if element is selected (checkboxes/radio buttons)
206
 * @param selector - Element selector
207
 * @returns Promise resolving with selected boolean
208
 */
209
browser.isSelected(selector: string): Promise<boolean>;
210
```
211

212
**Usage Examples:**
213

214
```javascript
215
// Check element states
216
browser.isVisible("#modal").then(visible => {
217
  if (visible) {
218
    browser.click("#modal .close-button");
219
  }
220
});
221

222
browser.isEnabled("#submit-button").then(enabled => {
223
  if (enabled) {
224
    browser.click("#submit-button");
225
  }
226
});
227
```
228

229
### Element Properties
230

231
Access element properties, attributes, and text content.
232

233
```javascript { .api }
234
/**
235
 * Get element text content
236
 * @param selector - Element selector
237
 * @returns Promise resolving with text content
238
 */
239
browser.getText(selector: string): Promise<string>;
240

241
/**
242
 * Get element input value
243
 * @param selector - Element selector
244
 * @returns Promise resolving with input value
245
 */
246
browser.getValue(selector: string): Promise<string>;
247

248
/**
249
 * Get element attribute value
250
 * @param selector - Element selector
251
 * @param attribute - Attribute name
252
 * @returns Promise resolving with attribute value
253
 */
254
browser.getAttribute(selector: string, attribute: string): Promise<string>;
255

256
/**
257
 * Set element attribute
258
 * @param selector - Element selector
259
 * @param attribute - Attribute name
260
 * @param value - Attribute value
261
 * @returns Promise resolving when attribute set
262
 */
263
browser.setAttribute(selector: string, attribute: string, value: string);
264

265
/**
266
 * Get CSS property value
267
 * @param selector - Element selector
268
 * @param property - CSS property name
269
 * @returns Promise resolving with property value
270
 */
271
browser.getCssProperty(selector: string, property: string): Promise<string>;
272

273
/**
274
 * Get DOM property value
275
 * @param selector - Element selector
276
 * @param property - Property name
277
 * @returns Promise resolving with property value
278
 */
279
browser.getElementProperty(selector: string, property: string): Promise<any>;
280

281
/**
282
 * Get element tag name
283
 * @param selector - Element selector
284
 * @returns Promise resolving with tag name
285
 */
286
browser.getTagName(selector: string): Promise<string>;
287

288
/**
289
 * Get element accessible name
290
 * @param selector - Element selector
291
 * @returns Promise resolving with accessible name
292
 */
293
browser.getAccessibleName(selector: string): Promise<string>;
294

295
/**
296
 * Get element ARIA role
297
 * @param selector - Element selector
298
 * @returns Promise resolving with ARIA role
299
 */
300
browser.getAriaRole(selector: string): Promise<string>;
301
```
302

303
**Usage Examples:**
304

305
```javascript
306
// Get element properties
307
browser.getText("#status-message").then(message => {
308
  console.log("Status:", message);
309
});
310

311
browser.getAttribute("img", "src").then(src => {
312
  console.log("Image source:", src);
313
});
314

315
browser.getCssProperty("#header", "background-color").then(color => {
316
  console.log("Header color:", color);
317
});
318
```
319

320
### Element Geometry
321

322
Get element dimensions, position, and layout information.
323

324
```javascript { .api }
325
/**
326
 * Get element dimensions
327
 * @param selector - Element selector
328
 * @returns Promise resolving with size object
329
 */
330
browser.getElementSize(selector: string): Promise<{width: number, height: number}>;
331

332
/**
333
 * Get element rectangle properties
334
 * @param selector - Element selector
335
 * @returns Promise resolving with rectangle object
336
 */
337
browser.getElementRect(selector: string): Promise<{x: number, y: number, width: number, height: number}>;
338

339
/**
340
 * Get element position coordinates
341
 * @param selector - Element selector
342
 * @returns Promise resolving with position object
343
 */
344
browser.getLocation(selector: string): Promise<{x: number, y: number}>;
345

346
/**
347
 * Get element position in viewport
348
 * @param selector - Element selector
349
 * @returns Promise resolving with viewport position
350
 */
351
browser.getLocationInView(selector: string): Promise<{x: number, y: number}>;
352
```
353

354
**Usage Examples:**
355

356
```javascript
357
// Get element geometry
358
browser.getElementSize("#sidebar").then(size => {
359
  console.log(`Sidebar: ${size.width}x${size.height}`);
360
});
361

362
browser.getLocation("#button").then(pos => {
363
  console.log(`Button at: ${pos.x}, ${pos.y}`);
364
});
365
```
366

367
### Element Tree Navigation
368

369
Navigate between related elements in the DOM tree.
370

371
```javascript { .api }
372
/**
373
 * Get first child element
374
 * @param selector - Parent element selector
375
 * @returns Promise resolving with first child element
376
 */
377
browser.getFirstElementChild(selector: string): Promise<WebElement>;
378

379
/**
380
 * Get last child element
381
 * @param selector - Parent element selector
382
 * @returns Promise resolving with last child element
383
 */
384
browser.getLastElementChild(selector: string): Promise<WebElement>;
385

386
/**
387
 * Get next sibling element
388
 * @param selector - Element selector
389
 * @returns Promise resolving with next sibling element
390
 */
391
browser.getNextSibling(selector: string): Promise<WebElement>;
392

393
/**
394
 * Get previous sibling element
395
 * @param selector - Element selector
396
 * @returns Promise resolving with previous sibling element
397
 */
398
browser.getPreviousSibling(selector: string): Promise<WebElement>;
399

400
/**
401
 * Check if element has child elements
402
 * @param selector - Element selector
403
 * @returns Promise resolving with boolean indicating children presence
404
 */
405
browser.hasDescendants(selector: string): Promise<boolean>;
406

407
/**
408
 * Get shadow DOM root
409
 * @param selector - Element selector
410
 * @returns Promise resolving with shadow root
411
 */
412
browser.getShadowRoot(selector: string): Promise<ShadowRoot>;
413
```
414

415
**Usage Examples:**
416

417
```javascript
418
// Navigate element tree
419
browser.getFirstElementChild("ul").then(firstItem => {
420
  console.log("First list item found");
421
});
422

423
browser.getNextSibling("#current-item").then(nextItem => {
424
  browser.click(nextItem);
425
});
426
```
427

428
### Element Actions
429

430
Advanced element interaction operations.
431

432
```javascript { .api }
433
/**
434
 * Move mouse to element with optional offset
435
 * @param selector - Element selector
436
 * @param xOffset - X offset from element center
437
 * @param yOffset - Y offset from element center
438
 * @returns Promise resolving when mouse moved
439
 */
440
browser.moveToElement(selector: string, xOffset?: number, yOffset?: number);
441

442
/**
443
 * Drag element to target location
444
 * @param source - Source element selector
445
 * @param target - Target element selector
446
 * @returns Promise resolving when drag completed
447
 */
448
browser.dragAndDrop(source: string, target: string);
449

450
/**
451
 * Take screenshot of specific element
452
 * @param selector - Element selector
453
 * @returns Promise resolving when screenshot taken
454
 */
455
browser.takeElementScreenshot(selector: string);
456

457
/**
458
 * Check checkbox or radio button
459
 * @param selector - Checkbox/radio selector
460
 * @returns Promise resolving when element checked
461
 */
462
browser.check(selector: string);
463

464
/**
465
 * Uncheck checkbox or radio button
466
 * @param selector - Checkbox/radio selector
467
 * @returns Promise resolving when element unchecked
468
 */
469
browser.uncheck(selector: string);
470
```
471

472
**Usage Examples:**
473

474
```javascript
475
// Advanced interactions
476
browser.moveToElement("#dropdown-trigger");
477
browser.dragAndDrop("#draggable-item", "#drop-zone");
478
browser.check("input[type='checkbox'][name='agree']");
479
browser.takeElementScreenshot("#chart");
480
```
481

482
### Element Waiting
483

484
Wait for elements to reach desired states before proceeding.
485

486
```javascript { .api }
487
/**
488
 * Wait for element to be present in DOM
489
 * @param selector - Element selector
490
 * @param timeout - Maximum wait time in milliseconds
491
 * @returns Promise resolving when element present
492
 */
493
browser.waitForElementPresent(selector: string, timeout?: number);
494

495
/**
496
 * Wait for element to be visible
497
 * @param selector - Element selector
498
 * @param timeout - Maximum wait time in milliseconds
499
 * @returns Promise resolving when element visible
500
 */
501
browser.waitForElementVisible(selector: string, timeout?: number);
502

503
/**
504
 * Wait for element to be absent from DOM
505
 * @param selector - Element selector
506
 * @param timeout - Maximum wait time in milliseconds
507
 * @returns Promise resolving when element not present
508
 */
509
browser.waitForElementNotPresent(selector: string, timeout?: number);
510

511
/**
512
 * Wait for element to be invisible
513
 * @param selector - Element selector
514
 * @param timeout - Maximum wait time in milliseconds
515
 * @returns Promise resolving when element not visible
516
 */
517
browser.waitForElementNotVisible(selector: string, timeout?: number);
518
```
519

520
**Usage Examples:**
521

522
```javascript
523
// Wait for elements
524
browser.waitForElementVisible("#loading-spinner", 5000);
525
browser.waitForElementNotVisible("#loading-spinner", 10000);
526
browser.waitForElementPresent("#results", 3000);
527

528
// Chain operations after waiting
529
browser
530
  .waitForElementVisible("#modal", 2000)
531
  .click("#modal .confirm-button")
532
  .waitForElementNotVisible("#modal", 2000);
533
```