0
# WD WebDriver Client
1

2
WD is a comprehensive WebDriver/Selenium 2 Node.js client library that provides automated browser testing and web scraping capabilities. It offers multiple programming paradigms including pure async callbacks, Q promises with chaining, and promise-based APIs, supporting all major browsers through the JsonWire Protocol and W3C WebDriver standards.
3

4
## Package Information
5

6
- **Package Name**: wd
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install wd`
10

11
## Core Imports
12

13
```javascript
14
// Choose your preferred API style
15
const wd = require('wd');
16

17
// Pure async callbacks (default)
18
const browser = wd.remote();
19

20
// Q promises without chaining
21
const browser = wd.promiseRemote();
22

23
// Q promises with chaining (most popular)
24
const browser = wd.promiseChainRemote();
25

26
// Or explicitly specify type
27
const browser = wd.remote('promiseChain');
28
```
29

30
ES6 modules:
31

32
```javascript
33
import wd from 'wd';
34
const browser = wd.promiseChainRemote();
35
```
36

37
## Basic Usage
38

39
### Promise Chain Style (Recommended)
40

41
```javascript
42
const wd = require('wd');
43
const browser = wd.promiseChainRemote();
44

45
browser
46
  .init({browserName: 'chrome'})
47
  .get('http://example.com')
48
  .title()
49
  .then(title => console.log('Page title:', title))
50
  .elementById('submit-button')
51
  .click()
52
  .sleep(1000)
53
  .quit();
54
```
55

56
### Pure Async Style
57

58
```javascript
59
const wd = require('wd');
60
const browser = wd.remote();
61

62
browser.init({browserName: 'chrome'}, function(err) {
63
  if (err) throw err;
64
  browser.get('http://example.com', function(err) {
65
    if (err) throw err;
66
    browser.title(function(err, title) {
67
      console.log('Page title:', title);
68
      browser.quit();
69
    });
70
  });
71
});
72
```
73

74
### Promise Style (No Chaining)
75

76
```javascript
77
const wd = require('wd');
78
const browser = wd.promiseRemote();
79

80
async function example() {
81
  await browser.init({browserName: 'chrome'});
82
  await browser.get('http://example.com');
83
  const title = await browser.title();
84
  console.log('Page title:', title);
85
  await browser.quit();
86
}
87
```
88

89
## Architecture
90

91
WD is built around several key components:
92

93
- **WebDriver Core**: Main browser automation engine implementing JsonWire Protocol
94
- **Element API**: Rich element interaction and inspection capabilities
95
- **Actions System**: Touch gestures, mouse actions, and W3C Actions support
96
- **Promise Wrappers**: Multiple async patterns (callbacks, promises, promise chains)
97
- **Mobile Support**: Full Appium integration for iOS and Android testing
98
- **Extension System**: Custom method addition and configuration capabilities
99

100
## Capabilities
101

102
### Browser Sessions
103

104
Core session management for initializing, configuring, and terminating browser instances. Supports local Selenium servers and cloud services like Sauce Labs.
105

106
```javascript { .api }
107
// Factory functions for different async patterns
108
function remote(configUrl?: string | object, driverType?: string): Webdriver;
109
function promiseRemote(configUrl?: string | object): PromiseWebdriver;
110
function promiseChainRemote(configUrl?: string | object): PromiseChainWebdriver;
111
function asyncRemote(configUrl?: string | object): Webdriver;
112
```
113

114
[Browser Sessions](./browser-sessions.md)
115

116
### Navigation & Page Interaction
117

118
Navigation commands for browsing web pages, managing browser history, and retrieving page information.
119

120
```javascript { .api }
121
// Core navigation methods
122
get(url: string, cb?: callback): void;
123
refresh(cb?: callback): void;
124
back(cb?: callback): void;
125
forward(cb?: callback): void;
126
url(cb?: callback): void;
127
title(cb?: callback): void;
128
source(cb?: callback): void;
129
```
130

131
[Navigation](./navigation.md)
132

133
### Element Location & Interaction
134

135
Comprehensive element finding, interaction, and inspection capabilities with multiple selector strategies.
136

137
```javascript { .api }
138
// Element finding methods
139
element(using: string, value: string, cb?: callback): Element;
140
elements(using: string, value: string, cb?: callback): Element[];
141
elementById(id: string, cb?: callback): Element;
142
elementByClassName(className: string, cb?: callback): Element;
143
elementByCss(selector: string, cb?: callback): Element;
144
elementByXPath(xpath: string, cb?: callback): Element;
145
```
146

147
[Element Location](./element-location.md)
148

149
### User Input & Actions
150

151
Mouse interactions, keyboard input, touch gestures, and W3C Actions for complex user interactions.
152

153
```javascript { .api }
154
// Input methods
155
keys(keys: string | string[], cb?: callback): void;
156
click(button?: number, cb?: callback): void;
157
doubleclick(cb?: callback): void;
158
moveTo(element?: Element, xOffset?: number, yOffset?: number, cb?: callback): void;
159
```
160

161
[User Input](./user-input.md)
162

163
### Waiting & Synchronization
164

165
Powerful waiting mechanisms with built-in asserters for handling dynamic content and asynchronous operations.
166

167
```javascript { .api }
168
// Waiting methods
169
waitFor(asserter: Asserter, timeout?: number, pollFreq?: number, cb?: callback): void;
170
waitForElement(using: string, value: string, timeout?: number, cb?: callback): Element;
171
waitForVisible(using: string, value: string, timeout?: number, pollFreq?: number, cb?: callback): Element;
172
```
173

174
[Waiting](./waiting.md)
175

176
### JavaScript Execution
177

178
Execute JavaScript code in the browser context with safe evaluation and error handling.
179

180
```javascript { .api }
181
// JavaScript execution methods
182
execute(code: string | function, args?: any[], cb?: callback): any;
183
safeExecute(code: string | function, args?: any[], cb?: callback): any;
184
executeAsync(code: string | function, args?: any[], cb?: callback): any;
185
eval(code: string, cb?: callback): any;
186
```
187

188
[JavaScript Execution](./javascript-execution.md)
189

190
### Window & Frame Management
191

192
Multi-window and frame handling for complex web applications.
193

194
```javascript { .api }
195
// Window management methods
196
windowHandles(cb?: callback): string[];
197
window(windowHandle: string, cb?: callback): void;
198
close(cb?: callback): void;
199
frame(frameRef: string | number | null, cb?: callback): void;
200
```
201

202
[Window Management](./window-management.md)
203

204
### Mobile Testing
205

206
Comprehensive mobile testing support through Appium integration with device-specific actions and capabilities.
207

208
```javascript { .api }
209
// Mobile device actions
210
shakeDevice(cb?: callback): void;
211
lockDevice(seconds?: number, cb?: callback): void;
212
rotateDevice(x: number, y: number, z: number, cb?: callback): void;
213
getCurrentActivity(cb?: callback): string;
214
```
215

216
[Mobile Testing](./mobile-testing.md)
217

218
### Touch Actions & Gestures
219

220
Advanced touch gesture support using TouchAction and MultiAction builders for mobile and touch-enabled devices.
221

222
```javascript { .api }
223
// Touch action classes
224
class TouchAction {
225
  constructor(driver: Webdriver);
226
  tap(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
227
  press(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
228
  moveTo(opts?: {element?: Element, x?: number, y?: number}): TouchAction;
229
  release(): TouchAction;
230
  wait(ms: number): TouchAction;
231
  perform(cb?: callback): void;
232
}
233
```
234

235
[Touch Actions](./touch-actions.md)
236

237
### Configuration & Extension
238

239
HTTP configuration, timeout settings, and custom method addition for extending the library.
240

241
```javascript { .api }
242
// Configuration methods
243
configureHttp(opts: {timeout?: number, retries?: number, retryDelay?: number}): void;
244
addAsyncMethod(name: string, method: function): void;
245
addPromiseMethod(name: string, method: function): void;
246
```
247

248
[Configuration](./configuration.md)
249

250
## Types & Interfaces
251

252
```javascript { .api }
253
// Core classes
254
class Webdriver extends EventEmitter {
255
  constructor(configUrl: string | object);
256
  // Methods defined in capabilities above
257
}
258

259
class Element {
260
  constructor(value: string, browser: Webdriver);
261
  value: string;
262
  browser: Webdriver;
263
  // Element-specific methods
264
}
265

266
// Promise wrapper classes
267
class PromiseWebdriver extends Webdriver {
268
  // All methods return promises instead of using callbacks
269
}
270

271
class PromiseChainWebdriver extends Webdriver {
272
  // All methods return chainable promises
273
}
274

275
// Configuration types
276
interface DesiredCapabilities {
277
  browserName?: string;
278
  version?: string;
279
  platform?: string;
280
  javascriptEnabled?: boolean;
281
  acceptSslCerts?: boolean;
282
  [key: string]: any;
283
}
284

285
interface HttpConfig {
286
  timeout?: number;
287
  retries?: number;
288
  retryDelay?: number;
289
  baseUrl?: string;
290
  proxy?: string;
291
}
292
```
293

294
## Utilities
295

296
```javascript { .api }
297
// Utility objects and functions
298
const SPECIAL_KEYS: {
299
  NULL: string;
300
  Tab: string;
301
  Enter: string;
302
  Shift: string;
303
  Control: string;
304
  Alt: string;
305
  Escape: string;
306
  Space: string;
307
  // ... more special keys
308
};
309

310
const asserters: {
311
  nonEmptyText: Asserter;
312
  textInclude(content: string): Asserter;
313
  isDisplayed: Asserter;
314
  isNotDisplayed: Asserter;
315
  jsCondition(jsExpr: string, safe?: boolean): Asserter;
316
};
317

318
// Base asserter class
319
class Asserter {
320
  constructor(assertFunction: (target: any, callback: function) => void);
321
}
322
```