0
# Session Management
1

2
Core session creation and management functionality for initializing WebDriver connections and managing browser instances.
3

4
## Capabilities
5

6
### Remote Session Creation
7

8
Creates a new WebdriverIO session with specified capabilities and configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a new WebdriverIO session
13
 * @param params - Configuration object including capabilities and WebDriver options
14
 * @param remoteModifier - Optional function to modify the remote instance
15
 * @returns Promise resolving to a Browser instance
16
 */
17
function remote(params: Capabilities.WebdriverIOConfig, remoteModifier?: Function): Promise<WebdriverIO.Browser>;
18

19
interface Capabilities.WebdriverIOConfig {
20
  capabilities: object;
21
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
22
  connectionRetryTimeout?: number;
23
  connectionRetryCount?: number;
24
  automationProtocol?: 'webdriver' | 'devtools';
25
  baseUrl?: string;
26
  waitforTimeout?: number;
27
  waitforInterval?: number;
28
  region?: string;
29
  hostname?: string;
30
  port?: number;
31
  path?: string;
32
  protocol?: 'http' | 'https';
33
  user?: string;
34
  key?: string;
35
  services?: any[];
36
  reporters?: any[];
37
  framework?: string;
38
  mochaOpts?: object;
39
  jasmineOpts?: object;
40
  cucumberOpts?: object;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import { remote } from "webdriverio";
48

49
// Basic Chrome session
50
const browser = await remote({
51
  capabilities: {
52
    browserName: 'chrome'
53
  }
54
});
55

56
// Advanced configuration with custom options
57
const browser = await remote({
58
  capabilities: {
59
    browserName: 'firefox',
60
    'moz:firefoxOptions': {
61
      args: ['--headless']
62
    }
63
  },
64
  logLevel: 'debug',
65
  waitforTimeout: 10000,
66
  baseUrl: 'https://example.com'
67
});
68

69
// Mobile session using Appium
70
const driver = await remote({
71
  capabilities: {
72
    platformName: 'iOS',
73
    'appium:deviceName': 'iPhone Simulator',
74
    'appium:app': '/path/to/app.ipa'
75
  },
76
  hostname: 'localhost',
77
  port: 4723,
78
  path: '/wd/hub'
79
});
80
```
81

82
### Session Attachment
83

84
Attaches to an existing WebDriver session using its session ID.
85

86
```typescript { .api }
87
/**
88
 * Attaches to an existing WebDriver session
89
 * @param attachOptions - Options including session ID and protocol details
90
 * @returns Promise resolving to a Browser instance
91
 */
92
function attach(attachOptions: AttachOptions): Promise<WebdriverIO.Browser>;
93

94
interface AttachOptions {
95
  sessionId: string;
96
  isW3C?: boolean;
97
  commandTimeout?: number;
98
  hostname?: string;
99
  port?: number;
100
  path?: string;
101
  protocol?: 'http' | 'https';
102
}
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { attach } from "webdriverio";
109

110
// Attach to existing session
111
const browser = await attach({
112
  sessionId: '4f9e8e8a-7b1c-4d2e-9a5f-6c8d7e9f0a1b'
113
});
114

115
// Attach with custom endpoint
116
const browser = await attach({
117
  sessionId: '4f9e8e8a-7b1c-4d2e-9a5f-6c8d7e9f0a1b',
118
  hostname: 'selenium-hub.example.com',
119
  port: 4444,
120
  path: '/wd/hub'
121
});
122
```
123

124
### Multi-Remote Sessions
125

126
Creates multiple remote sessions for parallel multi-browser testing scenarios.
127

128
```typescript { .api }
129
/**
130
 * Creates multiple remote sessions for multi-browser testing
131
 * @param params - Configuration object mapping instance names to capabilities
132
 * @param options - Optional automation protocol specification
133
 * @returns Promise resolving to a MultiRemoteBrowser instance
134
 */
135
function multiremote(
136
  params: Capabilities.RequestedMultiremoteCapabilities, 
137
  options?: {automationProtocol?: string}
138
): Promise<WebdriverIO.MultiRemoteBrowser>;
139

140
interface Capabilities.RequestedMultiremoteCapabilities {
141
  [instanceName: string]: {
142
    capabilities: object;
143
    [key: string]: any;
144
  };
145
}
146

147
interface WebdriverIO.MultiRemoteBrowser {
148
  [instanceName: string]: WebdriverIO.Browser;
149
  sync(instanceNames?: string[]): Promise<void>;
150
  select(instanceName: string): WebdriverIO.Browser;
151
}
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { multiremote } from "webdriverio";
158

159
// Multi-browser testing setup
160
const matrix = await multiremote({
161
  chrome: {
162
    capabilities: {
163
      browserName: 'chrome'
164
    }
165
  },
166
  firefox: {
167
    capabilities: {
168
      browserName: 'firefox'
169
    }
170
  },
171
  safari: {
172
    capabilities: {
173
      browserName: 'safari'
174
    }
175
  }
176
});
177

178
// Navigate all browsers to the same page
179
await matrix.url('https://example.com');
180

181
// Interact with specific browsers
182
await matrix.chrome.$('#chrome-specific').click();
183
await matrix.firefox.$('#firefox-specific').click();
184

185
// Synchronize all browsers
186
await matrix.sync();
187

188
// Execute commands on all browsers in parallel
189
const titles = await matrix.getTitle();
190
console.log(titles); // { chrome: 'Title', firefox: 'Title', safari: 'Title' }
191
```
192

193
### Session Configuration
194

195
Default configuration options and constants used throughout WebdriverIO.
196

197
```typescript { .api }
198
const WDIO_DEFAULTS: {
199
  automationProtocol: 'webdriver';
200
  waitforTimeout: 3000;
201
  waitforInterval: 500;
202
  connectionRetryTimeout: 120000;
203
  connectionRetryCount: 3;
204
  logLevel: 'info';
205
  coloredLogs: true;
206
  deprecationWarnings: true;
207
  bail: 0;
208
  screenshotPath: './errorShots/';
209
  baseUrl: null;
210
  specs: [];
211
  suites: {};
212
  exclude: [];
213
  reporters: ['spec'];
214
  services: [];
215
  framework: 'mocha';
216
  mochaOpts: {
217
    timeout: 10000;
218
  };
219
  jasmineOpts: {
220
    defaultTimeoutInterval: 10000;
221
  };
222
  cucumberOpts: {
223
    timeout: 10000;
224
  };
225
};
226
```
227

228
### Session Lifecycle
229

230
Methods for managing session state and lifecycle.
231

232
```typescript { .api }
233
/**
234
 * Reload the WebDriver session, maintaining the same capabilities
235
 * @returns Promise that resolves when session is reloaded
236
 */
237
reloadSession(): Promise<void>;
238

239
/**
240
 * End the WebDriver session and close all associated windows
241
 * @returns Promise that resolves when session is closed
242
 */
243
deleteSession(): Promise<void>;
244

245
/**
246
 * Get the current session ID
247
 * @returns The session identifier string
248
 */
249
getSessionId(): string;
250

251
/**
252
 * Get the session capabilities
253
 * @returns Object containing the session capabilities
254
 */
255
getCapabilities(): object;
256
```
257

258
### Error Handling
259

260
WebdriverIO-specific error classes for session management failures.
261

262
```typescript { .api }
263
class SevereServiceError extends Error {
264
  name: 'SevereServiceError';
265
  message: string;
266
  stack?: string;
267
  
268
  constructor(message: string);
269
}
270
```
271

272
This error is thrown when critical service failures occur that prevent normal session operation, such as WebDriver server crashes or network connectivity issues that cannot be recovered from automatically.