0
# Configuration Options
1

2
WebdriverIO client and test runner configuration including connection settings, logging, test execution options, and service integrations.
3

4
## Capabilities
5

6
### Connection Configuration
7

8
WebDriver server connection settings and authentication.
9

10
```typescript { .api }
11
/**
12
 * WebDriver connection configuration
13
 */
14
interface Connection {
15
  /** Protocol: http or https */
16
  protocol?: string;
17
  /** WebDriver server hostname */
18
  hostname?: string;
19
  /** WebDriver server port */
20
  port?: number;
21
  /** Path to WebDriver endpoint */
22
  path?: string;
23
  /** Query parameters for driver server */
24
  queryParams?: Record<string, string>;
25
  /** Username for cloud services or authentication */
26
  user?: string;
27
  /** Access key or password for authentication */
28
  key?: string;
29
}
30
```
31

32
### WebDriver Client Options
33

34
Core WebDriver client configuration extending connection settings.
35

36
```typescript { .api }
37
/**
38
 * WebDriver client configuration
39
 */
40
interface WebDriver extends Connection {
41
  /** Logging verbosity level */
42
  logLevel?: WebDriverLogTypes;
43
  /** Per-logger log levels */
44
  logLevels?: Record<string, WebDriverLogTypes>;
45
  /** Connection retry timeout in milliseconds */
46
  connectionRetryTimeout?: number;
47
  /** Number of connection retry attempts */
48
  connectionRetryCount?: number;
49
  /** Custom headers for requests */
50
  headers?: Record<string, string>;
51
  /** Transform request options */
52
  transformRequest?: (requestOptions: RequestLibOptions) => RequestLibOptions;
53
  /** Transform response data */
54
  transformResponse?: (response: RequestLibResponse, requestOptions: RequestLibOptions) => RequestLibResponse;
55
  /** Strict SSL verification */
56
  strictSSL?: boolean;
57
  /** Custom agent for requests */
58
  agent?: any;
59
  /** Request/response logging */
60
  logRequests?: boolean;
61
  logResponses?: boolean;
62
}
63

64
/**
65
 * WebDriver log levels
66
 */
67
type WebDriverLogTypes = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
68

69
/**
70
 * HTTP methods
71
 */
72
type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'HEAD' | 'DELETE' | 'OPTIONS' | 'TRACE' | 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete' | 'options' | 'trace';
73
```
74

75
### WebdriverIO Options
76

77
WebdriverIO-specific configuration extending WebDriver client options.
78

79
```typescript { .api }
80
/**
81
 * WebdriverIO client configuration
82
 */
83
interface WebdriverIO extends WebDriver {
84
  /** WebDriver automation protocol */
85
  automationProtocol?: 'webdriver' | 'devtools' | 'stub';
86
  /** Base URL for navigation commands */
87
  baseUrl?: string;
88
  /** Wait timeout for expect assertions */
89
  waitforTimeout?: number;
90
  /** Interval for wait polling */
91
  waitforInterval?: number;
92
  /** Regional Sauce Labs data center */
93
  region?: SauceRegions;
94
  /** Enable WebDriver Bidi */
95
  enableDirectConnect?: boolean;
96
  /** Custom command wrapper */
97
  customCommandWrapper?: (commandName: string, fn: Function) => (...args: any[]) => any;
98
  /** Transform command execution */
99
  transformCommandLogOutput?: (result: any) => any;
100
}
101

102
/**
103
 * Sauce Labs regions
104
 */
105
type SauceRegions = 'us' | 'eu' | 'us-west-1' | 'us-east-4' | 'eu-central-1' | 'staging';
106
```
107

108
### Test Runner Configuration
109

110
Complete test runner configuration including test execution, reporting, and service integration.
111

112
```typescript { .api }
113
/**
114
 * Test runner configuration
115
 */
116
interface Testrunner extends Hooks, WebdriverIO {
117
  /** Test specification file patterns */
118
  specs?: string[];
119
  /** Files to exclude from test execution */
120
  exclude?: string[];
121
  /** Named test suites */
122
  suites?: Record<string, string[]>;
123
  /** Test execution capabilities */
124
  capabilities: TestrunnerCapabilities;
125
  /** Maximum concurrent test instances */
126
  maxInstances?: number;
127
  /** Maximum instances per capability */
128
  maxInstancesPerCapability?: number;
129
  /** Test framework (mocha, jasmine, cucumber) */
130
  framework: string;
131
  /** Framework-specific options */
132
  mochaOpts?: WebdriverIO.MochaOpts;
133
  jasmineOpts?: WebdriverIO.JasmineOpts;
134
  cucumberOpts?: WebdriverIO.CucumberOpts;
135
  /** Test reporters */
136
  reporters?: ReporterEntry[];
137
  /** Services for extending functionality */
138
  services?: ServiceEntry[];
139
  /** Bail on first test failure */
140
  bail?: number;
141
  /** Output directory for logs and reports */
142
  outputDir?: string;
143
  /** Connection options */
144
  connectionRetryTimeout?: number;
145
  connectionRetryCount?: number;
146
  /** Debug mode */
147
  debug?: boolean;
148
  /** Execute tests */
149
  execArgv?: string[];
150
  /** Force exit after tests */
151
  forceExit?: boolean;
152
  /** Watch mode options */
153
  watch?: boolean;
154
  filesToWatch?: string[];
155
  /** Spec file retry attempts */
156
  specFileRetries?: number;
157
  specFileRetriesDelay?: number;
158
  specFileRetriesDeferred?: boolean;
159
  /** Grouping and sharding */
160
  groupLogsByTestSpec?: boolean;
161
  shard?: ShardOptions;
162
  /** Runner selection */
163
  runner?: string | RunnerClass;
164
  /** Root directory */
165
  rootDir?: string;
166
  /** TypeScript configuration */
167
  tsConfigPath?: string;
168
  tsConfigPathsOptions?: TSConfigPathsOptions;
169
  /** Auto-compilation options */
170
  autoCompileOpts?: {
171
    autoCompile?: boolean;
172
    tsNodeOpts?: Record<string, any>;
173
    babelOpts?: Record<string, any>;
174
  };
175
}
176
```
177

178
### Sharding Configuration
179

180
Test execution sharding for parallel test distribution.
181

182
```typescript { .api }
183
/**
184
 * Test sharding configuration
185
 */
186
interface ShardOptions {
187
  /** Total number of shards */
188
  total: number;
189
  /** Current shard index (starts from 1) */
190
  current: number;
191
}
192
```
193

194
### TypeScript Configuration
195

196
TypeScript path mapping and compilation options.
197

198
```typescript { .api }
199
/**
200
 * TypeScript configuration options
201
 */
202
interface TSConfigPathsOptions {
203
  /** Base URL for path mapping */
204
  baseUrl?: string;
205
  /** Path mapping configuration */
206
  paths?: Record<string, string[]>;
207
  /** Additional TypeScript options */
208
  addMatchAll?: boolean;
209
}
210
```
211

212
### Request/Response Interfaces
213

214
HTTP request and response type definitions.
215

216
```typescript { .api }
217
/**
218
 * HTTP response structure
219
 */
220
interface RequestLibResponse<Body = unknown> {
221
  /** HTTP status code */
222
  statusCode: number;
223
  /** Parsed response body */
224
  body?: Body;
225
  /** Raw response buffer */
226
  rawBody?: Buffer;
227
}
228

229
/**
230
 * HTTP request options
231
 */
232
interface RequestLibOptions {
233
  /** Request method */
234
  method?: Method;
235
  /** Request URL */
236
  url?: string;
237
  /** Request headers */
238
  headers?: Record<string, string>;
239
  /** Request body */
240
  body?: any;
241
  /** JSON flag */
242
  json?: boolean;
243
  /** Form data flag */
244
  form?: boolean;
245
  /** Timeout */
246
  timeout?: number;
247
  /** Follow redirects */
248
  followRedirect?: boolean;
249
  /** Max redirects */
250
  maxRedirects?: number;
251
  /** Proxy settings */
252
  proxy?: string;
253
  /** SSL verification */
254
  strictSSL?: boolean;
255
}
256
```
257

258
### Runner Event Types
259

260
Test runner lifecycle event data structures.
261

262
```typescript { .api }
263
/**
264
 * Runner start event data
265
 */
266
interface RunnerStart {
267
  /** Capability ID */
268
  cid: string;
269
  /** Test specifications */
270
  specs: string[];
271
  /** Runner capabilities */
272
  capabilities: WebdriverIO.Capabilities;
273
  /** Session ID */
274
  sessionId?: string;
275
  /** Is multiremote */
276
  isMultiremote?: boolean;
277
  /** Instance options */
278
  instanceOptions?: Record<string, any>;
279
}
280

281
/**
282
 * Runner end event data
283
 */
284
interface RunnerEnd {
285
  /** Capability ID */
286
  cid: string;
287
  /** Test specifications */
288
  specs: string[];
289
  /** Runner capabilities */
290
  capabilities: WebdriverIO.Capabilities;
291
  /** Session ID */
292
  sessionId?: string;
293
  /** Is multiremote */
294
  isMultiremote?: boolean;
295
  /** Exit code */
296
  failures: number;
297
  /** Retry count */
298
  retries: number;
299
}
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
import type { Options } from "@wdio/types";
306

307
// Basic WebdriverIO configuration
308
const config: Options.Testrunner = {
309
  specs: ["./test/**/*.spec.ts"],
310
  capabilities: [{
311
    browserName: "chrome",
312
    "goog:chromeOptions": {
313
      args: ["--headless"]
314
    }
315
  }],
316
  baseUrl: "https://example.com",
317
  framework: "mocha",
318
  reporters: ["spec"],
319
  services: ["chromedriver"],
320
  mochaOpts: {
321
    timeout: 60000
322
  },
323
  waitforTimeout: 10000,
324
  connectionRetryTimeout: 120000,
325
  connectionRetryCount: 3,
326
  logLevel: "info"
327
};
328

329
// Connection configuration for remote WebDriver
330
const remoteConfig: Options.WebdriverIO = {
331
  protocol: "https",
332
  hostname: "hub.browserstack.com",
333
  port: 443,
334
  path: "/wd/hub",
335
  user: process.env.BROWSERSTACK_USERNAME,
336
  key: process.env.BROWSERSTACK_ACCESS_KEY,
337
  logLevel: "warn",
338
  connectionRetryTimeout: 180000
339
};
340
```