0
# Protocol Commands
1

2
Low-level WebDriver protocol commands for fine-grained browser control and automation, providing direct access to the WebDriver specification.
3

4
## Capabilities
5

6
### Session Management
7

8
Control WebDriver sessions at the protocol level.
9

10
```javascript { .api }
11
/**
12
 * WebDriver session operations
13
 * @param options - Session configuration options
14
 * @returns Promise resolving with session data
15
 */
16
browser.session(options?: SessionOptions): Promise<SessionData>;
17

18
/**
19
 * Get active WebDriver sessions
20
 * @returns Promise resolving with array of session info
21
 */
22
browser.sessions(): Promise<SessionInfo[]>;
23

24
/**
25
 * Get WebDriver server status
26
 * @returns Promise resolving with server status
27
 */
28
browser.status(): Promise<ServerStatus>;
29

30
/**
31
 * Quit WebDriver session
32
 * @returns Promise resolving when session terminated
33
 */
34
browser.quit(): Promise<void>;
35

36
/**
37
 * Session configuration options
38
 */
39
interface SessionOptions {
40
  desiredCapabilities?: Capabilities;
41
  requiredCapabilities?: Capabilities;
42
}
43

44
/**
45
 * Session data interface
46
 */
47
interface SessionData {
48
  sessionId: string;
49
  capabilities: Capabilities;
50
}
51

52
/**
53
 * Session information interface
54
 */
55
interface SessionInfo {
56
  id: string;
57
  capabilities: Capabilities;
58
}
59

60
/**
61
 * Server status interface
62
 */
63
interface ServerStatus {
64
  ready: boolean;
65
  message: string;
66
  uptime?: number;
67
}
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
// Check server status
74
browser.status().then(status => {
75
  console.log('WebDriver server ready:', status.ready);
76
});
77

78
// Get active sessions
79
browser.sessions().then(sessions => {
80
  console.log('Active sessions:', sessions.length);
81
});
82
```
83

84
### Browser Navigation Protocol
85

86
Low-level navigation commands using WebDriver protocol.
87

88
```javascript { .api }
89
/**
90
 * Navigate to URL using WebDriver protocol
91
 * @param url - URL to navigate to
92
 * @returns Promise resolving when navigation completes
93
 */
94
browser.navigateTo(url: string): Promise<void>;
95

96
/**
97
 * Get current page URL
98
 * @returns Promise resolving with current URL
99
 */
100
browser.getCurrentUrl(): Promise<string>;
101

102
/**
103
 * Navigate back in browser history
104
 * @returns Promise resolving when navigation completes
105
 */
106
browser.back(): Promise<void>;
107

108
/**
109
 * Navigate forward in browser history
110
 * @returns Promise resolving when navigation completes
111
 */
112
browser.forward(): Promise<void>;
113

114
/**
115
 * Refresh current page
116
 * @returns Promise resolving when page reloads
117
 */
118
browser.refresh(): Promise<void>;
119
```
120

121
**Usage Examples:**
122

123
```javascript
124
// Protocol-level navigation
125
browser
126
  .navigateTo('https://example.com')
127
  .getCurrentUrl()
128
  .then(url => console.log('Current URL:', url))
129
  .back()
130
  .forward()
131
  .refresh();
132
```
133

134
### Window and Frame Protocol
135

136
Protocol-level window and frame management.
137

138
```javascript { .api }
139
/**
140
 * Get current window handle
141
 * @returns Promise resolving with window handle
142
 */
143
browser.windowHandle(): Promise<string>;
144

145
/**
146
 * Get all window handles
147
 * @returns Promise resolving with array of window handles
148
 */
149
browser.windowHandles(): Promise<string[]>;
150

151
/**
152
 * Switch to window by handle
153
 * @param handle - Window handle to switch to
154
 * @returns Promise resolving when switch completes
155
 */
156
browser.switchToWindow(handle: string): Promise<void>;
157

158
/**
159
 * Close current window
160
 * @returns Promise resolving when window closed
161
 */
162
browser.closeWindow(): Promise<void>;
163

164
/**
165
 * Open new browser window
166
 * @param type - Window type ('tab' or 'window')
167
 * @returns Promise resolving with new window handle
168
 */
169
browser.openNewWindow(type?: 'tab' | 'window'): Promise<string>;
170

171
/**
172
 * Switch to frame by ID or index
173
 * @param id - Frame ID, index, or element
174
 * @returns Promise resolving when frame switched
175
 */
176
browser.frame(id: string | number | WebElement): Promise<void>;
177

178
/**
179
 * Switch to parent frame
180
 * @returns Promise resolving when switched to parent
181
 */
182
browser.frameParent(): Promise<void>;
183

184
/**
185
 * Get/set window position
186
 * @param x - X coordinate (optional)
187
 * @param y - Y coordinate (optional)
188
 * @returns Promise resolving with position or void
189
 */
190
browser.windowPosition(x?: number, y?: number): Promise<{x: number, y: number} | void>;
191

192
/**
193
 * Get/set window size
194
 * @param width - Window width (optional)
195
 * @param height - Window height (optional)
196
 * @returns Promise resolving with size or void
197
 */
198
browser.windowSize(width?: number, height?: number): Promise<{width: number, height: number} | void>;
199

200
/**
201
 * Get/set window rectangle
202
 * @param rect - Rectangle properties (optional)
203
 * @returns Promise resolving with rectangle or void
204
 */
205
browser.windowRect(rect?: WindowRect): Promise<WindowRect | void>;
206

207
/**
208
 * Maximize browser window
209
 * @returns Promise resolving when window maximized
210
 */
211
browser.windowMaximize(): Promise<void>;
212

213
/**
214
 * Minimize browser window
215
 * @returns Promise resolving when window minimized
216
 */
217
browser.minimizeWindow(): Promise<void>;
218

219
/**
220
 * Set window to fullscreen
221
 * @returns Promise resolving when fullscreen set
222
 */
223
browser.fullscreenWindow(): Promise<void>;
224

225
/**
226
 * Window rectangle interface
227
 */
228
interface WindowRect {
229
  x: number;
230
  y: number;
231
  width: number;
232
  height: number;
233
}
234
```
235

236
**Usage Examples:**
237

238
```javascript
239
// Window management
240
browser
241
  .windowHandle()
242
  .then(handle => console.log('Current window:', handle))
243
  .openNewWindow('tab')
244
  .then(newHandle => {
245
    console.log('New window:', newHandle);
246
    return browser.switchToWindow(newHandle);
247
  })
248
  .windowMaximize()
249
  .windowRect({x: 100, y: 100, width: 1024, height: 768});
250

251
// Frame handling
252
browser
253
  .frame('content-frame')
254
  .findElement('#frame-content')
255
  .frameParent();
256
```
257

258
### Element Protocol Operations
259

260
WebDriver protocol element operations using element IDs.
261

262
```javascript { .api }
263
/**
264
 * Find element using WebDriver protocol
265
 * @param strategy - Locate strategy
266
 * @param selector - Element selector
267
 * @returns Promise resolving with element
268
 */
269
browser.element(strategy: LocateStrategy, selector: string): Promise<WebElement>;
270

271
/**
272
 * Find elements using WebDriver protocol
273
 * @param strategy - Locate strategy
274
 * @param selector - Elements selector
275
 * @returns Promise resolving with elements array
276
 */
277
browser.elements(strategy: LocateStrategy, selector: string): Promise<WebElement[]>;
278

279
/**
280
 * Get currently active element
281
 * @returns Promise resolving with active element
282
 */
283
browser.elementActive(): Promise<WebElement>;
284

285
/**
286
 * Click element by WebDriver ID
287
 * @param id - WebDriver element ID
288
 * @returns Promise resolving when click completes
289
 */
290
browser.elementIdClick(id: string): Promise<void>;
291

292
/**
293
 * Get element text by WebDriver ID
294
 * @param id - WebDriver element ID
295
 * @returns Promise resolving with element text
296
 */
297
browser.elementIdText(id: string): Promise<string>;
298

299
/**
300
 * Get/set element value by WebDriver ID
301
 * @param id - WebDriver element ID
302
 * @param value - Value to set (optional)
303
 * @returns Promise resolving with value or void
304
 */
305
browser.elementIdValue(id: string, value?: string): Promise<string | void>;
306

307
/**
308
 * Get element attribute by WebDriver ID
309
 * @param id - WebDriver element ID
310
 * @param name - Attribute name
311
 * @returns Promise resolving with attribute value
312
 */
313
browser.elementIdAttribute(id: string, name: string): Promise<string>;
314

315
/**
316
 * Get element property by WebDriver ID
317
 * @param id - WebDriver element ID
318
 * @param name - Property name
319
 * @returns Promise resolving with property value
320
 */
321
browser.elementIdProperty(id: string, name: string): Promise<any>;
322

323
/**
324
 * Get CSS property by WebDriver ID
325
 * @param id - WebDriver element ID
326
 * @param name - CSS property name
327
 * @returns Promise resolving with property value
328
 */
329
browser.elementIdCssProperty(id: string, name: string): Promise<string>;
330

331
/**
332
 * Check if element is selected by WebDriver ID
333
 * @param id - WebDriver element ID
334
 * @returns Promise resolving with selected boolean
335
 */
336
browser.elementIdSelected(id: string): Promise<boolean>;
337

338
/**
339
 * Check if element is enabled by WebDriver ID
340
 * @param id - WebDriver element ID
341
 * @returns Promise resolving with enabled boolean
342
 */
343
browser.elementIdEnabled(id: string): Promise<boolean>;
344

345
/**
346
 * Check if element is displayed by WebDriver ID
347
 * @param id - WebDriver element ID
348
 * @returns Promise resolving with displayed boolean
349
 */
350
browser.elementIdDisplayed(id: string): Promise<boolean>;
351

352
/**
353
 * Get element location by WebDriver ID
354
 * @param id - WebDriver element ID
355
 * @returns Promise resolving with location coordinates
356
 */
357
browser.elementIdLocation(id: string): Promise<{x: number, y: number}>;
358

359
/**
360
 * Get element viewport location by WebDriver ID
361
 * @param id - WebDriver element ID
362
 * @returns Promise resolving with viewport coordinates
363
 */
364
browser.elementIdLocationInView(id: string): Promise<{x: number, y: number}>;
365

366
/**
367
 * Get element size by WebDriver ID
368
 * @param id - WebDriver element ID
369
 * @returns Promise resolving with element dimensions
370
 */
371
browser.elementIdSize(id: string): Promise<{width: number, height: number}>;
372

373
/**
374
 * Clear element by WebDriver ID
375
 * @param id - WebDriver element ID
376
 * @returns Promise resolving when element cleared
377
 */
378
browser.elementIdClear(id: string): Promise<void>;
379

380
/**
381
 * Double-click element by WebDriver ID
382
 * @param id - WebDriver element ID
383
 * @returns Promise resolving when double-click completes
384
 */
385
browser.elementIdDoubleClick(id: string): Promise<void>;
386

387
/**
388
 * Compare elements by WebDriver ID
389
 * @param id1 - First element ID
390
 * @param id2 - Second element ID
391
 * @returns Promise resolving with equality boolean
392
 */
393
browser.elementIdEquals(id1: string, id2: string): Promise<boolean>;
394

395
/**
396
 * Get element tag name by WebDriver ID
397
 * @param id - WebDriver element ID
398
 * @returns Promise resolving with tag name
399
 */
400
browser.elementIdName(id: string): Promise<string>;
401
```
402

403
**Usage Examples:**
404

405
```javascript
406
// Protocol-level element operations
407
browser
408
  .element('css selector', '#submit-button')
409
  .then(element => {
410
    console.log('Element ID:', element.ELEMENT);
411
    return browser.elementIdClick(element.ELEMENT);
412
  });
413

414
// Get element properties using protocol
415
browser
416
  .elements('css selector', '.menu-item')
417
  .then(elements => {
418
    elements.forEach((el, index) => {
419
      browser.elementIdText(el.ELEMENT).then(text => {
420
        console.log(`Menu item ${index}:`, text);
421
      });
422
    });
423
  });
424
```
425

426
### Mouse and Keyboard Protocol
427

428
Low-level mouse and keyboard operations.
429

430
```javascript { .api }
431
/**
432
 * Move mouse to coordinates or element
433
 * @param element - Element to move to (optional)
434
 * @param xOffset - X offset from element center
435
 * @param yOffset - Y offset from element center
436
 * @returns Promise resolving when mouse moved
437
 */
438
browser.moveTo(element?: WebElement, xOffset?: number, yOffset?: number): Promise<void>;
439

440
/**
441
 * Click mouse button
442
 * @param button - Mouse button (0=left, 1=middle, 2=right)
443
 * @returns Promise resolving when click completes
444
 */
445
browser.mouseButtonClick(button: 0 | 1 | 2): Promise<void>;
446

447
/**
448
 * Press mouse button down
449
 * @param button - Mouse button (0=left, 1=middle, 2=right)
450
 * @returns Promise resolving when button pressed
451
 */
452
browser.mouseButtonDown(button: 0 | 1 | 2): Promise<void>;
453

454
/**
455
 * Release mouse button
456
 * @param button - Mouse button (0=left, 1=middle, 2=right)
457
 * @returns Promise resolving when button released
458
 */
459
browser.mouseButtonUp(button: 0 | 1 | 2): Promise<void>;
460

461
/**
462
 * Release all mouse buttons
463
 * @returns Promise resolving when buttons released
464
 */
465
browser.releaseMouseButton(): Promise<void>;
466

467
/**
468
 * Send keys to active element
469
 * @param keys - Keys to send (string or array)
470
 * @returns Promise resolving when keys sent
471
 */
472
browser.keys(keys: string | string[]): Promise<void>;
473
```
474

475
**Usage Examples:**
476

477
```javascript
478
// Protocol-level mouse operations
479
browser
480
  .element('css selector', '#draggable')
481
  .then(element => {
482
    return browser
483
      .moveTo(element)
484
      .mouseButtonDown(0) // Left button down
485
      .moveTo(null, 100, 50) // Move 100px right, 50px down
486
      .mouseButtonUp(0); // Release left button
487
  });
488

489
// Protocol-level keyboard operations
490
browser
491
  .elementActive()
492
  .then(() => {
493
    return browser.keys(['Hello', ' ', 'World', '\uE007']); // Enter key
494
  });
495
```
496

497
### Alert Dialog Protocol
498

499
Handle JavaScript alert dialogs using WebDriver protocol.
500

501
```javascript { .api }
502
/**
503
 * Accept JavaScript alert dialog
504
 * @returns Promise resolving when alert accepted
505
 */
506
browser.acceptAlert(): Promise<void>;
507

508
/**
509
 * Dismiss JavaScript alert dialog
510
 * @returns Promise resolving when alert dismissed
511
 */
512
browser.dismissAlert(): Promise<void>;
513

514
/**
515
 * Get JavaScript alert dialog text
516
 * @returns Promise resolving with alert text
517
 */
518
browser.getAlertText(): Promise<string>;
519

520
/**
521
 * Set JavaScript alert dialog text (for prompt dialogs)
522
 * @param text - Text to set in alert
523
 * @returns Promise resolving when text set
524
 */
525
browser.setAlertText(text: string): Promise<void>;
526
```
527

528
**Usage Examples:**
529

530
```javascript
531
// Handle alert dialogs
532
browser
533
  .click('#show-alert-button')
534
  .getAlertText()
535
  .then(alertText => {
536
    console.log('Alert message:', alertText);
537
    return browser.acceptAlert();
538
  });
539

540
// Handle prompt dialogs
541
browser
542
  .click('#show-prompt-button')
543
  .setAlertText('User input')
544
  .acceptAlert();
545
```
546

547
### Cookie Protocol
548

549
Manage cookies using WebDriver protocol.
550

551
```javascript { .api }
552
/**
553
 * Cookie protocol operations
554
 * @param method - HTTP method for cookie operation
555
 * @param cookie - Cookie data (for set operations)
556
 * @returns Promise resolving with cookie data or void
557
 */
558
browser.cookie(method: 'GET'): Promise<Cookie[]>;
559
browser.cookie(method: 'POST', cookie: Cookie): Promise<void>;
560
browser.cookie(method: 'DELETE'): Promise<void>;
561
browser.cookie(method: 'DELETE', cookie: {name: string}): Promise<void>;
562
```
563

564
**Usage Examples:**
565

566
```javascript
567
// Protocol-level cookie operations
568
browser
569
  .cookie('POST', {
570
    name: 'session_id',
571
    value: 'abc123',
572
    domain: 'example.com'
573
  })
574
  .cookie('GET')
575
  .then(cookies => {
576
    console.log('All cookies:', cookies);
577
  })
578
  .cookie('DELETE', {name: 'session_id'});
579
```
580

581
### Timeout Configuration
582

583
Configure WebDriver timeout settings.
584

585
```javascript { .api }
586
/**
587
 * Set WebDriver timeouts
588
 * @param type - Timeout type
589
 * @param ms - Timeout in milliseconds
590
 * @returns Promise resolving when timeout set
591
 */
592
browser.timeouts(type: TimeoutType, ms: number): Promise<void>;
593
browser.timeouts(timeouts: TimeoutConfig): Promise<void>;
594

595
/**
596
 * Set async script timeout
597
 * @param ms - Timeout in milliseconds
598
 * @returns Promise resolving when timeout set
599
 */
600
browser.timeoutsAsyncScript(ms: number): Promise<void>;
601

602
/**
603
 * Set implicit wait timeout
604
 * @param ms - Timeout in milliseconds
605
 * @returns Promise resolving when timeout set
606
 */
607
browser.timeoutsImplicitWait(ms: number): Promise<void>;
608

609
/**
610
 * Timeout type options
611
 */
612
type TimeoutType = 'script' | 'implicit' | 'pageLoad';
613

614
/**
615
 * Timeout configuration interface
616
 */
617
interface TimeoutConfig {
618
  script?: number;
619
  implicit?: number;
620
  pageLoad?: number;
621
}
622
```
623

624
**Usage Examples:**
625

626
```javascript
627
// Configure timeouts
628
browser
629
  .timeouts('implicit', 10000) // 10 second implicit wait
630
  .timeoutsAsyncScript(30000)  // 30 second script timeout
631
  .timeouts({
632
    script: 30000,
633
    implicit: 10000,
634
    pageLoad: 60000
635
  });
636
```
637

638
### Content and Screenshot Protocol
639

640
Get page content and capture screenshots using protocol commands.
641

642
```javascript { .api }
643
/**
644
 * Take page screenshot
645
 * @returns Promise resolving with base64 screenshot data
646
 */
647
browser.screenshot(): Promise<string>;
648

649
/**
650
 * Get page HTML source
651
 * @returns Promise resolving with HTML source
652
 */
653
browser.source(): Promise<string>;
654

655
/**
656
 * Get page title
657
 * @returns Promise resolving with page title
658
 */
659
browser.title(): Promise<string>;
660

661
/**
662
 * Get/set current URL
663
 * @param url - URL to navigate to (optional)
664
 * @returns Promise resolving with URL or void
665
 */
666
browser.url(url?: string): Promise<string | void>;
667
```
668

669
**Usage Examples:**
670

671
```javascript
672
// Protocol content operations
673
browser
674
  .url('https://example.com')
675
  .title()
676
  .then(title => console.log('Page title:', title))
677
  .source()
678
  .then(html => console.log('HTML length:', html.length))
679
  .screenshot()
680
  .then(base64Data => {
681
    // Save screenshot data
682
    require('fs').writeFileSync('screenshot.png', base64Data, 'base64');
683
  });
684
```
685

686
### Mobile Protocol Commands (Appium)
687

688
Mobile-specific protocol commands for native app testing.
689

690
```javascript { .api }
691
/**
692
 * Get available mobile contexts
693
 * @returns Promise resolving with context names
694
 */
695
browser.contexts(): Promise<string[]>;
696

697
/**
698
 * Get current mobile context
699
 * @returns Promise resolving with current context
700
 */
701
browser.currentContext(): Promise<string>;
702

703
/**
704
 * Set mobile context
705
 * @param context - Context name ('NATIVE_APP', 'WEBVIEW_1', etc.)
706
 * @returns Promise resolving when context set
707
 */
708
browser.setContext(context: string): Promise<void>;
709

710
/**
711
 * Get device orientation
712
 * @returns Promise resolving with orientation
713
 */
714
browser.getOrientation(): Promise<'PORTRAIT' | 'LANDSCAPE'>;
715

716
/**
717
 * Set device orientation
718
 * @param orientation - Device orientation
719
 * @returns Promise resolving when orientation set
720
 */
721
browser.setOrientation(orientation: 'PORTRAIT' | 'LANDSCAPE'): Promise<void>;
722

723
/**
724
 * Get GPS coordinates
725
 * @returns Promise resolving with location
726
 */
727
browser.getGeolocation(): Promise<{latitude: number, longitude: number}>;
728

729
/**
730
 * Set GPS coordinates
731
 * @param location - GPS coordinates
732
 * @returns Promise resolving when location set
733
 */
734
browser.setGeolocation(location: {latitude: number, longitude: number}): Promise<void>;
735
```
736

737
**Usage Examples:**
738

739
```javascript
740
// Mobile protocol operations
741
if (browser.isMobile()) {
742
  browser
743
    .contexts()
744
    .then(contexts => {
745
      console.log('Available contexts:', contexts);
746
      if (contexts.includes('WEBVIEW_1')) {
747
        return browser.setContext('WEBVIEW_1');
748
      }
749
    })
750
    .setOrientation('LANDSCAPE')
751
    .setGeolocation({latitude: 37.7749, longitude: -122.4194});
752
}
753
```