0
# Configuration
1

2
WebdriverIO CLI provides comprehensive configuration options for all testing scenarios including multi-browser testing, cloud service integration, and custom test frameworks.
3

4
## Capabilities
5

6
### Run Command Arguments
7

8
Complete configuration interface for the run command, supporting all WebdriverIO testing scenarios.
9

10
```typescript { .api }
11
interface RunCommandArguments {
12
  /** Path to WebdriverIO configuration file */
13
  configPath: string;
14
  
15
  /** Enable watch mode for continuous testing */
16
  watch?: boolean;
17
  
18
  /** WebDriver server hostname */
19
  hostname?: string;
20
  
21
  /** WebDriver server port */
22
  port?: number;
23
  
24
  /** Path to WebDriver endpoints (default "/") */
25
  path?: string;
26
  
27
  /** Username for cloud service authentication */
28
  user?: string;
29
  
30
  /** Access key for cloud service authentication */
31
  key?: string;
32
  
33
  /** Logging verbosity level */
34
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
35
  
36
  /** Stop test execution after N failures */
37
  bail?: number;
38
  
39
  /** Base URL for test execution */
40
  baseUrl?: string;
41
  
42
  /** Shard configuration for parallel execution */
43
  shard?: Options.ShardOptions;
44
  
45
  /** Default wait timeout in milliseconds */
46
  waitforTimeout?: number;
47
  
48
  /** Test framework to use */
49
  framework?: string;
50
  
51
  /** Reporter configuration */
52
  reporters?: Reporters.ReporterEntry[];
53
  
54
  /** Test suites to execute */
55
  suite?: string[];
56
  
57
  /** Specific spec files to run */
58
  spec?: string[];
59
  
60
  /** Patterns to exclude from execution */
61
  exclude?: string[];
62
  
63
  /** Mocha framework options */
64
  mochaOpts?: WebdriverIO.MochaOpts;
65
  
66
  /** Jasmine framework options */
67
  jasmineOpts?: WebdriverIO.JasmineOpts;
68
  
69
  /** Cucumber framework options */
70
  cucumberOpts?: WebdriverIO.CucumberOpts;
71
  
72
  /** Enable code coverage collection */
73
  coverage?: boolean;
74
  
75
  /** Visual regression snapshot update mode */
76
  updateSnapshots?: Options.Testrunner['updateSnapshots'];
77
  
78
  /** TypeScript configuration file path */
79
  tsConfigPath?: string;
80
  
81
  /** Repeat specific specs and/or suites N times */
82
  repeat?: number;
83
  
84
  /** Internal: Services to ignore in workers */
85
  ignoredWorkerServices?: string[];
86
}
87
```
88

89
### REPL Command Arguments
90

91
Configuration for interactive WebDriver REPL sessions.
92

93
```typescript { .api }
94
interface ReplCommandArguments {
95
  /** Mobile platform version */
96
  platformVersion: string;
97
  
98
  /** Mobile device name */
99
  deviceName: string;
100
  
101
  /** Device unique identifier */
102
  udid: string;
103
  
104
  /** Browser or device option */
105
  option: string;
106
  
107
  /** WebDriver capabilities (JSON string or file path) */
108
  capabilities: string;
109
}
110
```
111

112
### Install Command Arguments
113

114
Configuration for WebdriverIO plugin installation.
115

116
```typescript { .api }
117
interface InstallCommandArguments {
118
  /** Configuration file path */
119
  config?: string;
120
  
121
  /** Type of package to install */
122
  type: 'service' | 'reporter' | 'framework' | 'plugin';
123
  
124
  /** Package name (without @wdio/ prefix) */
125
  name: string;
126
}
127
```
128

129
### Project Properties
130

131
Project metadata and configuration detection.
132

133
```typescript { .api }
134
interface ProjectProps {
135
  /** ESM module support detection */
136
  esmSupported: boolean;
137
  
138
  /** Project root path */
139
  path: string;
140
  
141
  /** Parsed package.json data */
142
  packageJson: NormalizedPackageJson;
143
}
144

145
/** Package information for supported WebdriverIO packages */
146
interface SupportedPackage {
147
  /** Full package name */
148
  package: string;
149
  
150
  /** Short name for CLI usage */
151
  short: string;
152
  
153
  /** Description of package purpose */
154
  purpose: string;
155
}
156
```
157

158
## Configuration Examples
159

160
### Basic Test Execution
161

162
```typescript
163
import { Launcher } from "@wdio/cli";
164

165
// Minimal configuration
166
const launcher = new Launcher("./wdio.conf.js");
167

168
// With basic options
169
const launcher = new Launcher("./wdio.conf.js", {
170
  logLevel: "info",
171
  bail: 1
172
});
173
```
174

175
### Environment-Specific Configuration
176

177
```typescript
178
// Development environment
179
const devLauncher = new Launcher("./wdio.conf.js", {
180
  baseUrl: "http://localhost:3000",
181
  logLevel: "debug",
182
  watch: true,
183
  spec: ["./test/specs/unit/**/*.js"]
184
});
185

186
// Staging environment
187
const stagingLauncher = new Launcher("./wdio.conf.js", {
188
  baseUrl: "https://staging.example.com",
189
  logLevel: "info",
190
  bail: 3,
191
  suite: ["smoke", "regression"]
192
});
193

194
// Production environment
195
const prodLauncher = new Launcher("./wdio.conf.js", {
196
  baseUrl: "https://example.com",
197
  logLevel: "warn",
198
  bail: 1,
199
  reporters: [["spec"], ["junit", { outputDir: "./test-results" }]]
200
});
201
```
202

203
### Cloud Service Configuration
204

205
```typescript
206
// Sauce Labs configuration
207
const sauceLauncher = new Launcher("./wdio.conf.js", {
208
  user: process.env.SAUCE_USERNAME,
209
  key: process.env.SAUCE_ACCESS_KEY,
210
  hostname: "ondemand.saucelabs.com",
211
  port: 443,
212
  path: "/wd/hub"
213
});
214

215
// BrowserStack configuration
216
const browserStackLauncher = new Launcher("./wdio.conf.js", {
217
  user: process.env.BROWSERSTACK_USERNAME,
218
  key: process.env.BROWSERSTACK_ACCESS_KEY,
219
  hostname: "hub-cloud.browserstack.com",
220
  port: 443
221
});
222
```
223

224
### Framework-Specific Configuration
225

226
```typescript
227
// Mocha framework
228
const mochaLauncher = new Launcher("./wdio.conf.js", {
229
  framework: "mocha",
230
  mochaOpts: {
231
    timeout: 60000,
232
    retries: 2,
233
    grep: "critical"
234
  }
235
});
236

237
// Jasmine framework
238
const jasmineLauncher = new Launcher("./wdio.conf.js", {
239
  framework: "jasmine",
240
  jasmineOpts: {
241
    defaultTimeoutInterval: 60000,
242
    stopSpecOnExpectationFailure: false,
243
    random: true
244
  }
245
});
246

247
// Cucumber framework
248
const cucumberLauncher = new Launcher("./wdio.conf.js", {
249
  framework: "cucumber",
250
  cucumberOpts: {
251
    timeout: 60000,
252
    strict: false,
253
    tags: "@smoke or @regression",
254
    require: ["./test/step-definitions/**/*.js"]
255
  }
256
});
257
```
258

259
### Advanced Configuration
260

261
```typescript
262
// Parallel execution with sharding
263
const shardedLauncher = new Launcher("./wdio.conf.js", {
264
  shard: {
265
    current: 1,
266
    total: 4
267
  },
268
  spec: ["./test/specs/**/*.js"],
269
  maxInstances: 5
270
});
271

272
// Coverage collection
273
const coverageLauncher = new Launcher("./wdio.conf.js", {
274
  coverage: true,
275
  reporters: [
276
    ["spec"],
277
    ["coverage", { 
278
      dir: "./coverage",
279
      reports: ["html", "lcov", "text"]
280
    }]
281
  ]
282
});
283

284
// Custom TypeScript configuration
285
const tsLauncher = new Launcher("./wdio.conf.js", {
286
  tsConfigPath: "./tsconfig.test.json",
287
  spec: ["./test/specs/**/*.ts"]
288
});
289
```
290

291
## Environment Variables
292

293
### Standard Environment Variables
294

295
```typescript
296
// Authentication
297
process.env.WDIO_USER = "username";
298
process.env.WDIO_KEY = "accesskey";
299

300
// Server configuration
301
process.env.WDIO_HOSTNAME = "selenium-server.com";
302
process.env.WDIO_PORT = "4444";
303
process.env.WDIO_PATH = "/wd/hub";
304

305
// Logging
306
process.env.WDIO_LOG_LEVEL = "debug";
307

308
// Base URL
309
process.env.WDIO_BASE_URL = "https://example.com";
310
```
311

312
### Cloud Service Environment Variables
313

314
```typescript
315
// Sauce Labs
316
process.env.SAUCE_USERNAME = "your-username";
317
process.env.SAUCE_ACCESS_KEY = "your-access-key";
318

319
// BrowserStack
320
process.env.BROWSERSTACK_USERNAME = "your-username";
321
process.env.BROWSERSTACK_ACCESS_KEY = "your-access-key";
322

323
// TestingBot
324
process.env.TB_KEY = "your-key";
325
process.env.TB_SECRET = "your-secret";
326

327
// LambdaTest
328
process.env.LT_USERNAME = "your-username";
329
process.env.LT_ACCESS_KEY = "your-access-key";
330
```
331

332
## Configuration Validation
333

334
### Type Safety
335

336
```typescript
337
import { RunCommandArguments } from "@wdio/cli";
338

339
// Type-safe configuration function
340
function createTestConfig(
341
  baseConfig: Partial<RunCommandArguments>
342
): RunCommandArguments {
343
  return {
344
    configPath: "./wdio.conf.js",
345
    logLevel: "info",
346
    bail: 0,
347
    ...baseConfig
348
  };
349
}
350

351
// Usage with validation
352
const config = createTestConfig({
353
  baseUrl: "https://example.com",
354
  suite: ["smoke"],
355
  logLevel: "debug" // TypeScript ensures valid log level
356
});
357
```
358

359
### Runtime Validation
360

361
```typescript
362
import { coerceOptsFor } from "@wdio/cli";
363

364
// Validate and coerce CLI options
365
const validatedOptions = coerceOptsFor({
366
  bail: "3",        // Coerced to number
367
  watch: "true",    // Coerced to boolean
368
  logLevel: "info", // Validated against allowed values
369
  spec: "test.js"   // Coerced to array
370
});
371
```
372

373
## Constants
374

375
### Default Configurations
376

377
```typescript { .api }
378
/** Android device default configuration */
379
const ANDROID_CONFIG = {
380
  platformName: 'Android',
381
  automationName: 'UiAutomator2',
382
  deviceName: 'Test'
383
};
384

385
/** iOS device default configuration */
386
const IOS_CONFIG = {
387
  platformName: 'iOS',
388
  automationName: 'XCUITest',
389
  deviceName: 'iPhone Simulator'
390
};
391

392
/** Supported CLI commands */
393
const SUPPORTED_COMMANDS = ['run', 'install', 'config', 'repl'];
394

395
/** Package metadata */
396
const pkg = {
397
  name: '@wdio/cli',
398
  version: '9.19.2',
399
  description: 'WebdriverIO testrunner command line interface'
400
  // ... additional package.json fields
401
};
402
```
403

404
### Testrunner Defaults
405

406
```typescript { .api }
407
/** Default testrunner configuration schema with validation */
408
const TESTRUNNER_DEFAULTS: Options.Definition<Options.Testrunner & { capabilities: unknown }> = {
409
  specs: {
410
    type: 'object',
411
    validate: (param: string[]) => {
412
      if (!Array.isArray(param)) {
413
        throw new Error('the "specs" option needs to be a list of strings');
414
      }
415
    }
416
  },
417
  exclude: {
418
    type: 'object',
419
    validate: (param: string[]) => {
420
      if (!Array.isArray(param)) {
421
        throw new Error('the "exclude" option needs to be a list of strings');
422
      }
423
    }
424
  },
425
  bail: {
426
    type: 'number',
427
    default: 0
428
  },
429
  // ... extensive configuration schema
430
};
431
```