0
# Modern Element API
1
2
Modern fluent element API providing chainable operations and built-in waiting mechanisms for improved test reliability and readability.
3
4
## Capabilities
5
6
### Element Creation
7
8
Create element wrappers that provide fluent, chainable interfaces for element operations.
9
10
```javascript { .api }
11
/**
12
* Create element wrapper for chainable operations
13
* @param selector - CSS selector or XPath
14
* @returns Element wrapper instance
15
*/
16
browser.element(selector: string): Element;
17
18
/**
19
* Find child element within current element
20
* @param selector - Child element selector
21
* @returns Child element wrapper
22
*/
23
element.find(selector: string): Element;
24
element.get(selector: string): Element; // Alias for find
25
26
/**
27
* Find multiple child elements within current element
28
* @param selector - Child elements selector
29
* @returns Array of child element wrappers
30
*/
31
element.findAll(selector: string): Element[];
32
element.getAll(selector: string): Element[]; // Alias for findAll
33
```
34
35
**Usage Examples:**
36
37
```javascript
38
// Create element wrapper
39
const loginForm = browser.element("#login-form");
40
const submitButton = loginForm.find("button[type='submit']");
41
42
// Chain operations
43
const menuItems = browser.element("#navigation").findAll(".menu-item");
44
```
45
46
### Element Queries by Content
47
48
Find elements using semantic content rather than technical selectors.
49
50
```javascript { .api }
51
/**
52
* Find element by visible text content
53
* @param text - Text content to search for
54
* @param options - Search options
55
* @returns Element wrapper
56
*/
57
element.findByText(text: string, options?: {exact?: boolean}): Element;
58
59
/**
60
* Find element by ARIA role
61
* @param role - ARIA role name
62
* @param options - Search options including accessible name
63
* @returns Element wrapper
64
*/
65
element.findByRole(role: string, options?: {name?: string}): Element;
66
67
/**
68
* Find element by placeholder text
69
* @param text - Placeholder text to search for
70
* @returns Element wrapper
71
*/
72
element.findByPlaceholderText(text: string): Element;
73
74
/**
75
* Find element by associated label text
76
* @param text - Label text to search for
77
* @returns Element wrapper
78
*/
79
element.findByLabelText(text: string): Element;
80
81
/**
82
* Find element by alt attribute text
83
* @param text - Alt text to search for
84
* @returns Element wrapper
85
*/
86
element.findByAltText(text: string): Element;
87
88
/**
89
* Find multiple elements by text content
90
* @param text - Text content to search for
91
* @param options - Search options
92
* @returns Array of element wrappers
93
*/
94
element.findAllByText(text: string, options?: {exact?: boolean}): Element[];
95
96
/**
97
* Find multiple elements by ARIA role
98
* @param role - ARIA role name
99
* @param options - Search options
100
* @returns Array of element wrappers
101
*/
102
element.findAllByRole(role: string, options?: {name?: string}): Element[];
103
104
/**
105
* Find multiple elements by placeholder text
106
* @param text - Placeholder text to search for
107
* @returns Array of element wrappers
108
*/
109
element.findAllByPlaceholderText(text: string): Element[];
110
111
/**
112
* Find multiple elements by label text
113
* @param text - Label text to search for
114
* @returns Array of element wrappers
115
*/
116
element.findAllByLabelText(text: string): Element[];
117
118
/**
119
* Find multiple elements by alt text
120
* @param text - Alt text to search for
121
* @returns Array of element wrappers
122
*/
123
element.findAllByAltText(text: string): Element[];
124
```
125
126
**Usage Examples:**
127
128
```javascript
129
// Semantic element finding
130
const loginButton = browser.element("body").findByRole("button", {name: "Log in"});
131
const emailInput = browser.element("form").findByLabelText("Email Address");
132
const searchInput = browser.element(".search").findByPlaceholderText("Search products...");
133
134
// Find multiple elements by content
135
const allButtons = browser.element("main").findAllByRole("button");
136
const productImages = browser.element(".gallery").findAllByAltText("Product Image");
137
```
138
139
### Element Actions
140
141
Perform actions on elements with built-in waiting and error handling.
142
143
```javascript { .api }
144
/**
145
* Click element
146
* @returns Promise resolving when click completes
147
*/
148
element.click(): Promise<void>;
149
150
/**
151
* Clear element content
152
* @returns Promise resolving when content cleared
153
*/
154
element.clear(): Promise<void>;
155
156
/**
157
* Send keystrokes to element
158
* @param keys - Keys to send
159
* @returns Promise resolving when keys sent
160
*/
161
element.sendKeys(...keys: string[]): Promise<void>;
162
163
/**
164
* Submit form containing element
165
* @returns Promise resolving when form submitted
166
*/
167
element.submit(): Promise<void>;
168
169
/**
170
* Check checkbox or radio button
171
* @returns Promise resolving when element checked
172
*/
173
element.check(): Promise<void>;
174
175
/**
176
* Uncheck checkbox or radio button
177
* @returns Promise resolving when element unchecked
178
*/
179
element.uncheck(): Promise<void>;
180
181
/**
182
* Drag element to destination
183
* @param destination - Target element or coordinates
184
* @returns Promise resolving when drag completes
185
*/
186
element.dragAndDrop(destination: Element | {x: number, y: number}): Promise<void>;
187
188
/**
189
* Move mouse to element with optional offset
190
* @param x - X offset from element center
191
* @param y - Y offset from element center
192
* @returns Promise resolving when mouse moved
193
*/
194
element.moveTo(x?: number, y?: number): Promise<void>;
195
196
/**
197
* Update element value (clear then set)
198
* @param keys - Keys to send after clearing
199
* @returns Promise resolving when value updated
200
*/
201
element.update(...keys: string[]): Promise<void>;
202
203
/**
204
* Upload file to file input element
205
* @param file - File path to upload
206
* @returns Promise resolving when file uploaded
207
*/
208
element.upload(file: string): Promise<void>;
209
210
/**
211
* Click and hold element
212
* @returns Promise resolving when click-and-hold completes
213
*/
214
element.clickAndHold(): Promise<void>;
215
216
/**
217
* Double-click element
218
* @returns Promise resolving when double-click completes
219
*/
220
element.doubleClick(): Promise<void>;
221
222
/**
223
* Right-click element
224
* @returns Promise resolving when right-click completes
225
*/
226
element.rightClick(): Promise<void>;
227
```
228
229
**Usage Examples:**
230
231
```javascript
232
// Fluent element actions
233
const form = browser.element("#contact-form");
234
await form.findByLabelText("Name").sendKeys("John Doe");
235
await form.findByLabelText("Email").sendKeys("john@example.com");
236
await form.findByRole("button", {name: "Submit"}).click();
237
238
// File upload
239
await browser.element("input[type='file']").upload("/path/to/document.pdf");
240
241
// Drag and drop
242
const draggable = browser.element("#draggable-item");
243
const dropZone = browser.element("#drop-zone");
244
await draggable.dragAndDrop(dropZone);
245
```
246
247
### Element Properties
248
249
Access element properties with promise-based return values.
250
251
```javascript { .api }
252
/**
253
* Get WebDriver element ID
254
* @returns Promise resolving with element ID
255
*/
256
element.getId(): Promise<string>;
257
258
/**
259
* Get element dimensions and position
260
* @returns Promise resolving with rectangle object
261
*/
262
element.getRect(): Promise<{x: number, y: number, width: number, height: number}>;
263
element.rect(): Promise<{x: number, y: number, width: number, height: number}>; // Alias
264
265
/**
266
* Get element dimensions
267
* @returns Promise resolving with size object
268
*/
269
element.getSize(): Promise<{width: number, height: number}>;
270
271
/**
272
* Get element position
273
* @returns Promise resolving with position object
274
*/
275
element.getLocation(): Promise<{x: number, y: number}>;
276
277
/**
278
* Get element tag name
279
* @returns Promise resolving with tag name
280
*/
281
element.getTagName(): Promise<string>;
282
element.tagName(): Promise<string>; // Alias
283
284
/**
285
* Get element text content
286
* @returns Promise resolving with text content
287
*/
288
element.getText(): Promise<string>;
289
element.text(): Promise<string>; // Alias
290
291
/**
292
* Get element input value
293
* @returns Promise resolving with input value
294
*/
295
element.getValue(): Promise<string>;
296
297
/**
298
* Get DOM property value
299
* @param name - Property name
300
* @returns Promise resolving with property value
301
*/
302
element.getProperty(name: string): Promise<any>;
303
element.prop(name: string): Promise<any>; // Alias
304
305
/**
306
* Set DOM property value
307
* @param name - Property name
308
* @param value - Property value
309
* @returns Promise resolving when property set
310
*/
311
element.setProperty(name: string, value: any): Promise<void>;
312
313
/**
314
* Get element attribute value
315
* @param name - Attribute name
316
* @returns Promise resolving with attribute value
317
*/
318
element.getAttribute(name: string): Promise<string>;
319
element.attr(name: string): Promise<string>; // Alias
320
321
/**
322
* Set element attribute value
323
* @param name - Attribute name
324
* @param value - Attribute value
325
* @returns Promise resolving when attribute set
326
*/
327
element.setAttribute(name: string, value: string): Promise<void>;
328
329
/**
330
* Get CSS property value
331
* @param name - CSS property name
332
* @returns Promise resolving with property value
333
*/
334
element.getCssProperty(name: string): Promise<string>;
335
element.css(name: string): Promise<string>; // Alias
336
337
/**
338
* Get element accessible name
339
* @returns Promise resolving with accessible name
340
*/
341
element.getAccessibleName(): Promise<string>;
342
element.accessibleName(): Promise<string>; // Alias
343
344
/**
345
* Get element ARIA role
346
* @returns Promise resolving with ARIA role
347
*/
348
element.getAriaRole(): Promise<string>;
349
element.ariaRole(): Promise<string>; // Alias
350
```
351
352
**Usage Examples:**
353
354
```javascript
355
// Get element properties
356
const button = browser.element("#submit-button");
357
const buttonText = await button.getText();
358
const isDisabled = await button.getProperty("disabled");
359
const backgroundColor = await button.getCssProperty("background-color");
360
361
console.log(`Button "${buttonText}" is ${isDisabled ? 'disabled' : 'enabled'}`);
362
console.log(`Background color: ${backgroundColor}`);
363
```
364
365
### Element State
366
367
Check element state with boolean return values.
368
369
```javascript { .api }
370
/**
371
* Check if element is enabled for interaction
372
* @returns Promise resolving with enabled boolean
373
*/
374
element.isEnabled(): Promise<boolean>;
375
376
/**
377
* Check if element exists in DOM
378
* @returns Promise resolving with presence boolean
379
*/
380
element.isPresent(): Promise<boolean>;
381
382
/**
383
* Check if element is selected (checkboxes/radio buttons)
384
* @returns Promise resolving with selected boolean
385
*/
386
element.isSelected(): Promise<boolean>;
387
388
/**
389
* Check if element is visible
390
* @returns Promise resolving with visibility boolean
391
*/
392
element.isVisible(): Promise<boolean>;
393
element.isDisplayed(): Promise<boolean>; // Alias
394
395
/**
396
* Check if element is currently active (has focus)
397
* @returns Promise resolving with active boolean
398
*/
399
element.isActive(): Promise<boolean>;
400
```
401
402
**Usage Examples:**
403
404
```javascript
405
// Check element state
406
const form = browser.element("#registration-form");
407
const submitButton = form.findByRole("button", {name: "Register"});
408
409
if (await submitButton.isEnabled()) {
410
await submitButton.click();
411
} else {
412
console.log("Submit button is disabled");
413
}
414
415
if (await form.findByLabelText("Terms").isSelected()) {
416
console.log("Terms checkbox is checked");
417
}
418
```
419
420
### Element Tree Navigation
421
422
Navigate between related elements using modern API.
423
424
```javascript { .api }
425
/**
426
* Get first child element
427
* @returns Promise resolving with first child element
428
*/
429
element.getFirstElementChild(): Promise<Element>;
430
431
/**
432
* Get last child element
433
* @returns Promise resolving with last child element
434
*/
435
element.getLastElementChild(): Promise<Element>;
436
437
/**
438
* Get next sibling element
439
* @returns Promise resolving with next sibling element
440
*/
441
element.getNextElementSibling(): Promise<Element>;
442
443
/**
444
* Get previous sibling element
445
* @returns Promise resolving with previous sibling element
446
*/
447
element.getPreviousElementSibling(): Promise<Element>;
448
449
/**
450
* Get shadow DOM root
451
* @returns Promise resolving with shadow root
452
*/
453
element.getShadowRoot(): Promise<ShadowRoot>;
454
```
455
456
**Usage Examples:**
457
458
```javascript
459
// Navigate DOM tree
460
const list = browser.element("ul.menu");
461
const firstItem = await list.getFirstElementChild();
462
const secondItem = await firstItem.getNextElementSibling();
463
464
await secondItem.click();
465
```
466
467
### Element Utilities
468
469
Additional utilities for advanced element operations.
470
471
```javascript { .api }
472
/**
473
* Take screenshot of element
474
* @returns Promise resolving when screenshot taken
475
*/
476
element.takeScreenshot(): Promise<void>;
477
478
/**
479
* Wait for element to meet custom condition
480
* @param condition - Function returning boolean or promise
481
* @param options - Wait options including timeout
482
* @returns Promise resolving when condition met
483
*/
484
element.waitUntil(
485
condition: (element: Element) => boolean | Promise<boolean>,
486
options?: {timeout?: number, message?: string}
487
): Promise<void>;
488
```
489
490
**Usage Examples:**
491
492
```javascript
493
// Take element screenshot
494
await browser.element("#chart").takeScreenshot();
495
496
// Wait for custom condition
497
const statusElement = browser.element("#status");
498
await statusElement.waitUntil(async (el) => {
499
const text = await el.getText();
500
return text === "Complete";
501
}, {timeout: 10000, message: "Status never became Complete"});
502
```
503
504
### Element Assertions
505
506
Built-in assertions for common element validation patterns.
507
508
```javascript { .api }
509
/**
510
* Assert element is enabled
511
* @returns Promise resolving when assertion passes
512
*/
513
element.assert.enabled(): Promise<void>;
514
515
/**
516
* Assert element is selected
517
* @returns Promise resolving when assertion passes
518
*/
519
element.assert.selected(): Promise<void>;
520
521
/**
522
* Assert element is visible
523
* @returns Promise resolving when assertion passes
524
*/
525
element.assert.visible(): Promise<void>;
526
527
/**
528
* Assert element is present in DOM
529
* @returns Promise resolving when assertion passes
530
*/
531
element.assert.present(): Promise<void>;
532
533
/**
534
* Assert element has specific CSS class
535
* @param name - CSS class name
536
* @returns Promise resolving when assertion passes
537
*/
538
element.assert.hasClass(name: string): Promise<void>;
539
540
/**
541
* Assert element has specific attribute
542
* @param name - Attribute name
543
* @returns Promise resolving when assertion passes
544
*/
545
element.assert.hasAttribute(name: string): Promise<void>;
546
547
/**
548
* Assert element has child elements
549
* @returns Promise resolving when assertion passes
550
*/
551
element.assert.hasDescendants(): Promise<void>;
552
```
553
554
**Usage Examples:**
555
556
```javascript
557
// Element assertions
558
const submitButton = browser.element("#submit-button");
559
await submitButton.assert.visible();
560
await submitButton.assert.enabled();
561
await submitButton.assert.hasAttribute("type");
562
563
const requiredField = browser.element("#email");
564
await requiredField.assert.hasAttribute("required");
565
```
566
567
### Element Value Assertions
568
569
Assertions for element text and value content.
570
571
```javascript { .api }
572
/**
573
* Assert element value contains expected text
574
* @param expected - Expected text content
575
* @returns Promise resolving when assertion passes
576
*/
577
elementValue.assert.contains(expected: string): Promise<void>;
578
579
/**
580
* Assert element value equals expected text
581
* @param expected - Expected text content
582
* @returns Promise resolving when assertion passes
583
*/
584
elementValue.assert.equals(expected: string): Promise<void>;
585
586
/**
587
* Assert element value matches regular expression
588
* @param regex - Regular expression pattern
589
* @returns Promise resolving when assertion passes
590
*/
591
elementValue.assert.matches(regex: RegExp): Promise<void>;
592
```
593
594
**Usage Examples:**
595
596
```javascript
597
// Value assertions
598
const emailInput = browser.element("#email");
599
await emailInput.sendKeys("user@example.com");
600
601
const emailValue = await emailInput.getValue();
602
await emailValue.assert.contains("@example.com");
603
await emailValue.assert.matches(/^[^@]+@[^@]+\.[^@]+$/);
604
605
const statusMessage = browser.element("#status");
606
const statusText = await statusMessage.getText();
607
await statusText.assert.equals("Operation completed successfully");
608
```