0
# Element Location & Interaction
1

2
Comprehensive element finding, interaction, and inspection capabilities with multiple selector strategies and robust element handling.
3

4
## Capabilities
5

6
### Element Finding
7

8
Locate elements using various selector strategies including ID, class name, CSS selectors, and XPath.
9

10
```javascript { .api }
11
/**
12
 * Find a single element using selector strategy
13
 * @param using - Selector strategy ('id', 'class name', 'css selector', 'xpath', etc.)
14
 * @param value - Selector value
15
 * @param cb - Callback receiving (err, element)
16
 */
17
element(using: string, value: string, cb?: callback): Element;
18

19
/**
20
 * Find multiple elements using selector strategy
21
 * @param using - Selector strategy
22
 * @param value - Selector value
23
 * @param cb - Callback receiving (err, elements)
24
 */
25
elements(using: string, value: string, cb?: callback): Element[];
26

27
/**
28
 * Find element by ID
29
 * @param id - Element ID attribute
30
 * @param cb - Callback receiving (err, element)
31
 */
32
elementById(id: string, cb?: callback): Element;
33

34
/**
35
 * Find element by class name
36
 * @param className - Element class name
37
 * @param cb - Callback receiving (err, element)
38
 */
39
elementByClassName(className: string, cb?: callback): Element;
40

41
/**
42
 * Find element by CSS selector
43
 * @param selector - CSS selector string
44
 * @param cb - Callback receiving (err, element)
45
 */
46
elementByCss(selector: string, cb?: callback): Element;
47

48
/**
49
 * Find element by XPath
50
 * @param xpath - XPath expression
51
 * @param cb - Callback receiving (err, element)
52
 */
53
elementByXPath(xpath: string, cb?: callback): Element;
54

55
/**
56
 * Find element by link text
57
 * @param text - Exact link text
58
 * @param cb - Callback receiving (err, element)
59
 */
60
elementByLinkText(text: string, cb?: callback): Element;
61

62
/**
63
 * Find element by partial link text
64
 * @param text - Partial link text
65
 * @param cb - Callback receiving (err, element)
66
 */
67
elementByPartialLinkText(text: string, cb?: callback): Element;
68

69
/**
70
 * Find element by tag name
71
 * @param tagName - HTML tag name
72
 * @param cb - Callback receiving (err, element)
73
 */
74
elementByTagName(tagName: string, cb?: callback): Element;
75

76
/**
77
 * Find element by name attribute
78
 * @param name - Element name attribute
79
 * @param cb - Callback receiving (err, element)
80
 */
81
elementByName(name: string, cb?: callback): Element;
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
// Find by ID
88
browser.elementById('submit-button', function(err, element) {
89
  if (err) throw err;
90
  console.log('Found submit button:', element);
91
});
92

93
// Find by CSS selector
94
browser.elementByCss('.login-form input[type="email"]', function(err, element) {
95
  // Found email input in login form
96
});
97

98
// Find multiple elements
99
browser.elementsByCss('.product-item', function(err, elements) {
100
  console.log('Found', elements.length, 'products');
101
});
102

103
// Promise chain style
104
browser
105
  .elementById('menu-toggle')
106
  .click()
107
  .elementByCss('.dropdown-menu')
108
  .isDisplayed()
109
  .then(visible => console.log('Menu visible:', visible));
110
```
111

112
### Safe Element Finding
113

114
Find elements with null return instead of errors when not found.
115

116
```javascript { .api }
117
/**
118
 * Find element or return null if not found
119
 * @param using - Selector strategy
120
 * @param value - Selector value
121
 * @param cb - Callback receiving (err, element | null)
122
 */
123
elementOrNull(using: string, value: string, cb?: callback): Element | null;
124

125
/**
126
 * Find element only if it exists
127
 * @param using - Selector strategy
128
 * @param value - Selector value
129
 * @param cb - Callback receiving (err, element | null)
130
 */
131
elementIfExists(using: string, value: string, cb?: callback): Element | null;
132

133
/**
134
 * Check if element exists without throwing error
135
 * @param using - Selector strategy
136
 * @param value - Selector value
137
 * @param cb - Callback receiving (err, exists)
138
 */
139
hasElement(using: string, value: string, cb?: callback): boolean;
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
// Safe element finding
146
browser.elementByIdOrNull('optional-element', function(err, element) {
147
  if (element) {
148
    // Element exists, interact with it
149
    element.click();
150
  } else {
151
    // Element doesn't exist, continue with test
152
    console.log('Optional element not found, skipping interaction');
153
  }
154
});
155

156
// Check element existence
157
browser.hasElement('css selector', '.error-message', function(err, exists) {
158
  if (exists) {
159
    console.log('Error message is displayed');
160
  }
161
});
162
```
163

164
### Element Properties & State
165

166
Retrieve element information, attributes, and state.
167

168
```javascript { .api }
169
/**
170
 * Get element text content
171
 * @param element - Target element
172
 * @param cb - Callback receiving (err, text)
173
 */
174
text(element: Element, cb?: callback): string;
175

176
/**
177
 * Get element attribute value
178
 * @param element - Target element
179
 * @param attrName - Attribute name
180
 * @param cb - Callback receiving (err, value)
181
 */
182
getAttribute(element: Element, attrName: string, cb?: callback): string;
183

184
/**
185
 * Get element tag name
186
 * @param element - Target element
187
 * @param cb - Callback receiving (err, tagName)
188
 */
189
getTagName(element: Element, cb?: callback): string;
190

191
/**
192
 * Get element value (for form inputs)
193
 * @param element - Target element
194
 * @param cb - Callback receiving (err, value)
195
 */
196
getValue(element: Element, cb?: callback): string;
197

198
/**
199
 * Check if element is displayed
200
 * @param element - Target element
201
 * @param cb - Callback receiving (err, isDisplayed)
202
 */
203
isDisplayed(element: Element, cb?: callback): boolean;
204

205
/**
206
 * Check if element is enabled
207
 * @param element - Target element
208
 * @param cb - Callback receiving (err, isEnabled)
209
 */
210
isEnabled(element: Element, cb?: callback): boolean;
211

212
/**
213
 * Check if element is selected (checkboxes, radio buttons)
214
 * @param element - Target element
215
 * @param cb - Callback receiving (err, isSelected)
216
 */
217
isSelected(element: Element, cb?: callback): boolean;
218

219
/**
220
 * Get computed CSS property value
221
 * @param element - Target element
222
 * @param cssProperty - CSS property name
223
 * @param cb - Callback receiving (err, value)
224
 */
225
getComputedCss(element: Element, cssProperty: string, cb?: callback): string;
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
// Get element information
232
browser.elementById('username', function(err, element) {
233
  element.text(function(err, text) {
234
    console.log('Username field text:', text);
235
  });
236
  
237
  element.getAttribute('placeholder', function(err, placeholder) {
238
    console.log('Placeholder text:', placeholder);
239
  });
240
  
241
  element.isDisplayed(function(err, visible) {
242
    console.log('Username field visible:', visible);
243
  });
244
});
245

246
// Check form field state
247
browser.elementById('terms-checkbox', function(err, checkbox) {
248
  checkbox.isSelected(function(err, checked) {
249
    if (!checked) {
250
      checkbox.click(); // Check the terms checkbox
251
    }
252
  });
253
});
254

255
// Get CSS styles
256
browser.elementByCss('.error-message', function(err, element) {
257
  element.getComputedCss('color', function(err, color) {
258
    console.log('Error message color:', color);
259
  });
260
});
261
```
262

263
### Element Location & Size
264

265
Get element positioning and dimensions.
266

267
```javascript { .api }
268
/**
269
 * Get element location on page
270
 * @param element - Target element
271
 * @param cb - Callback receiving (err, location)
272
 */
273
getLocation(element: Element, cb?: callback): {x: number, y: number};
274

275
/**
276
 * Get element location relative to viewport
277
 * @param element - Target element
278
 * @param cb - Callback receiving (err, location)
279
 */
280
getLocationInView(element: Element, cb?: callback): {x: number, y: number};
281

282
/**
283
 * Get element size
284
 * @param element - Target element
285
 * @param cb - Callback receiving (err, size)
286
 */
287
getSize(element: Element, cb?: callback): {width: number, height: number};
288
```
289

290
**Usage Examples:**
291

292
```javascript
293
// Get element position and size
294
browser.elementById('modal-dialog', function(err, modal) {
295
  modal.getLocation(function(err, location) {
296
    console.log('Modal position:', location.x, location.y);
297
  });
298
  
299
  modal.getSize(function(err, size) {
300
    console.log('Modal size:', size.width, size.height);
301
  });
302
});
303

304
// Center click on element
305
browser.elementByCss('.clickable-area', function(err, element) {
306
  element.getSize(function(err, size) {
307
    element.getLocation(function(err, location) {
308
      const centerX = location.x + size.width / 2;
309
      const centerY = location.y + size.height / 2;
310
      browser.moveTo(null, centerX, centerY);
311
      browser.click();
312
    });
313
  });
314
});
315
```
316

317
### Element Comparison
318

319
Compare elements for equality.
320

321
```javascript { .api }
322
/**
323
 * Compare two elements for equality
324
 * @param element1 - First element
325
 * @param element2 - Second element
326
 * @param cb - Callback receiving (err, areEqual)
327
 */
328
equalsElement(element1: Element, element2: Element, cb?: callback): boolean;
329
```
330

331
**Usage Examples:**
332

333
```javascript
334
// Compare elements
335
browser.elementById('current-user', function(err, userElement1) {
336
  browser.elementByCss('.user-profile', function(err, userElement2) {
337
    browser.equalsElement(userElement1, userElement2, function(err, areEqual) {
338
      console.log('Elements are the same:', areEqual);
339
    });
340
  });
341
});
342
```
343

344
### Active Element
345

346
Get the currently focused element.
347

348
```javascript { .api }
349
/**
350
 * Get the currently active (focused) element
351
 * @param cb - Callback receiving (err, element)
352
 */
353
active(cb?: callback): Element;
354
```
355

356
**Usage Examples:**
357

358
```javascript
359
// Get active element
360
browser.active(function(err, activeElement) {
361
  activeElement.getAttribute('id', function(err, id) {
362
    console.log('Currently focused element ID:', id);
363
  });
364
});
365

366
// Send keys to currently focused element
367
browser.active(function(err, element) {
368
  element.type('Hello World');
369
});
370
```