0
# Browser Sessions
1

2
Core session management functionality for initializing, configuring, and terminating browser instances. Supports local Selenium servers and cloud services like Sauce Labs and BrowserStack.
3

4
## Capabilities
5

6
### Factory Functions
7

8
Create WebDriver instances with different async patterns and configurations.
9

10
```javascript { .api }
11
/**
12
 * Create a WebDriver instance with configurable async pattern
13
 * @param configUrl - Server URL, config object, or connection parameters
14
 * @param driverType - 'async', 'promise', or 'promiseChain'
15
 */
16
function remote(configUrl?: string | object, driverType?: string): Webdriver;
17

18
/**
19
 * Create a promise-based WebDriver instance (no chaining)
20
 * @param configUrl - Server configuration
21
 */
22
function promiseRemote(configUrl?: string | object): PromiseWebdriver;
23

24
/**
25
 * Create a promise chain WebDriver instance
26
 * @param configUrl - Server configuration
27
 */
28
function promiseChainRemote(configUrl?: string | object): PromiseChainWebdriver;
29

30
/**
31
 * Create an async callback-based WebDriver instance
32
 * @param configUrl - Server configuration
33
 */
34
function asyncRemote(configUrl?: string | object): Webdriver;
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
const wd = require('wd');
41

42
// Connect to local Selenium server (default: http://127.0.0.1:4444/wd/hub)
43
const browser = wd.remote();
44

45
// Connect with explicit configuration
46
const browser = wd.remote({
47
  hostname: 'selenium.example.com',
48
  port: 4444,
49
  user: 'username',
50
  pwd: 'access-key'
51
});
52

53
// Connect to Sauce Labs
54
const browser = wd.remote('https://username:access-key@ondemand.saucelabs.com/wd/hub');
55

56
// Force promise chain pattern
57
const browser = wd.remote('promiseChain');
58
```
59

60
### Session Lifecycle
61

62
Initialize, attach to, and terminate browser sessions.
63

64
```javascript { .api }
65
/**
66
 * Initialize a new browser session with desired capabilities
67
 * @param desired - Browser capabilities object
68
 * @param cb - Callback receiving (err, sessionId, capabilities)
69
 */
70
init(desired: DesiredCapabilities, cb?: callback): void;
71

72
/**
73
 * Attach to an existing session by ID
74
 * @param sessionId - Existing session identifier
75
 * @param cb - Callback receiving (err)
76
 */
77
attach(sessionId: string, cb?: callback): void;
78

79
/**
80
 * Detach from current session without closing browser
81
 * @param cb - Callback receiving (err)
82
 */
83
detach(cb?: callback): void;
84

85
/**
86
 * Close browser and terminate session
87
 * @param cb - Callback receiving (err)
88
 */
89
quit(cb?: callback): void;
90

91
/**
92
 * Get current session ID
93
 * @param cb - Callback receiving (err, sessionId)
94
 */
95
getSessionId(cb?: callback): string;
96

97
interface DesiredCapabilities {
98
  browserName?: string;          // 'chrome', 'firefox', 'safari', 'internet explorer'
99
  version?: string;              // Browser version
100
  platform?: string;             // 'WINDOWS', 'MAC', 'LINUX', 'ANY'
101
  javascriptEnabled?: boolean;    // Enable JavaScript (default: true)
102
  acceptSslCerts?: boolean;      // Accept SSL certificates
103
  pageLoadStrategy?: string;     // 'normal', 'eager', 'none'
104
  proxy?: ProxyConfig;           // Proxy configuration
105
  [key: string]: any;           // Additional platform-specific capabilities
106
}
107

108
interface ProxyConfig {
109
  proxyType: string;            // 'direct', 'manual', 'pac', 'autodetect', 'system'
110
  httpProxy?: string;           // HTTP proxy server
111
  sslProxy?: string;            // SSL proxy server
112
  noProxy?: string[];           // Hosts to bypass proxy
113
}
114
```
115

116
**Usage Examples:**
117

118
```javascript
119
// Initialize Chrome browser
120
browser.init({
121
  browserName: 'chrome',
122
  chromeOptions: {
123
    args: ['--headless', '--no-sandbox']
124
  }
125
}, function(err, sessionId, capabilities) {
126
  if (err) throw err;
127
  console.log('Session started:', sessionId);
128
  // Browser is ready for automation
129
});
130

131
// Initialize with mobile emulation
132
browser.init({
133
  browserName: 'chrome',
134
  chromeOptions: {
135
    mobileEmulation: {
136
      deviceName: 'iPhone X'
137
    }
138
  }
139
});
140

141
// Initialize Firefox with profile
142
browser.init({
143
  browserName: 'firefox',
144
  'moz:firefoxOptions': {
145
    args: ['-headless'],
146
    prefs: {
147
      'dom.webnotifications.enabled': false
148
    }
149
  }
150
});
151
```
152

153
### Session Information
154

155
Retrieve information about the current session and server.
156

157
```javascript { .api }
158
/**
159
 * Get server status information
160
 * @param cb - Callback receiving (err, status)
161
 */
162
status(cb?: callback): object;
163

164
/**
165
 * Get all active sessions on the server
166
 * @param cb - Callback receiving (err, sessions)
167
 */
168
sessions(cb?: callback): object[];
169

170
/**
171
 * Get current session capabilities
172
 * @param cb - Callback receiving (err, capabilities)
173
 */
174
sessionCapabilities(cb?: callback): object;
175

176
/**
177
 * Get alternative session capabilities format
178
 * @param cb - Callback receiving (err, capabilities)
179
 */
180
altSessionCapabilities(cb?: callback): object;
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Check server status
187
browser.status(function(err, status) {
188
  console.log('WebDriver server status:', status);
189
  console.log('Ready:', status.ready);
190
  console.log('Message:', status.message);
191
});
192

193
// Get session capabilities
194
browser.sessionCapabilities(function(err, caps) {
195
  console.log('Browser name:', caps.browserName);
196
  console.log('Browser version:', caps.version);
197
  console.log('Platform:', caps.platform);
198
});
199
```
200

201
### Cloud Service Integration
202

203
Special integration features for cloud testing services.
204

205
```javascript { .api }
206
/**
207
 * Update Sauce Labs job information
208
 * @param jsonData - Job metadata to update
209
 * @param cb - Callback receiving (err)
210
 */
211
sauceJobUpdate(jsonData: object, cb?: callback): void;
212

213
/**
214
 * Set Sauce Labs job pass/fail status
215
 * @param hasPassed - Whether the test passed
216
 * @param cb - Callback receiving (err)
217
 */
218
sauceJobStatus(hasPassed: boolean, cb?: callback): void;
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
// Update Sauce Labs job with custom data
225
browser.sauceJobUpdate({
226
  name: 'My Test Suite',
227
  tags: ['smoke', 'login'],
228
  'custom-data': {
229
    release: '1.2.3',
230
    commit: 'abc123'
231
  }
232
});
233

234
// Mark test as passed/failed
235
browser.sauceJobStatus(true); // Test passed
236
```
237

238
### Error Handling
239

240
Handle common session errors and connection issues.
241

242
```javascript
243
// Common error patterns
244
browser.init(desiredCaps, function(err, sessionId) {
245
  if (err) {
246
    if (err.code === 'ECONNREFUSED') {
247
      console.error('Cannot connect to WebDriver server');
248
    } else if (err.seleniumError && err.seleniumError.type === 'SessionNotCreatedException') {
249
      console.error('Failed to create session:', err.message);
250
    } else {
251
      console.error('Initialization error:', err);
252
    }
253
    return;
254
  }
255
  
256
  // Session created successfully
257
  console.log('Session ID:', sessionId);
258
});
259
```