0
# Programmatic API
1

2
WebdriverIO CLI provides a comprehensive programmatic interface for integrating test execution into custom applications, CI/CD pipelines, and development tools.
3

4
## Capabilities
5

6
### Launcher Class
7

8
Main test orchestration class for programmatic WebdriverIO test execution. Handles configuration parsing, worker management, and test result aggregation.
9

10
```typescript { .api }
11
/**
12
 * Main test launcher class for programmatic test execution
13
 */
14
class Launcher {
15
  /**
16
   * Initialize launcher with configuration and options
17
   * @param configFilePath - Path to WebdriverIO configuration file
18
   * @param args - Additional command-line arguments and options
19
   * @param isWatchMode - Enable watch mode for continuous testing
20
   */
21
  constructor(
22
    configFilePath: string, 
23
    args?: RunCommandArguments, 
24
    isWatchMode?: boolean
25
  );
26

27
  /**
28
   * Execute test run and return exit code
29
   * @returns Promise resolving to exit code (0 for success) or undefined
30
   */
31
  run(): Promise<undefined | number>;
32

33
  // Properties
34
  readonly configParser: ConfigParser;
35
  readonly isMultiremote: boolean;
36
  readonly isParallelMultiremote: boolean;
37
  readonly runner?: Services.RunnerInstance;
38
  readonly interface?: CLInterface;
39
}
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { Launcher } from "@wdio/cli";
46

47
// Basic test execution
48
const launcher = new Launcher("./wdio.conf.js");
49
const exitCode = await launcher.run();
50

51
if (exitCode === 0) {
52
  console.log("All tests passed!");
53
} else {
54
  console.log(`Tests failed with exit code: ${exitCode}`);
55
}
56

57
// With custom options
58
const launcher = new Launcher("./wdio.conf.js", {
59
  spec: ["./test/specs/critical/*.js"],
60
  logLevel: "info",
61
  bail: 1,
62
  baseUrl: "https://staging.example.com"
63
});
64

65
// Watch mode for development
66
const launcher = new Launcher("./wdio.conf.js", {
67
  watch: true,
68
  spec: ["./test/specs/**/*.js"]
69
}, true);
70
```
71

72
### Run Function
73

74
Default CLI entry point function that processes command-line arguments and executes appropriate commands.
75

76
```typescript { .api }
77
/**
78
 * Main CLI entry point function
79
 * Processes command-line arguments and executes commands
80
 * @returns Promise resolving to false on error, void on success
81
 */
82
function run(): Promise<false | void>;
83
```
84

85
**Usage Examples:**
86

87
```typescript
88
import { run } from "@wdio/cli";
89

90
// Execute CLI with current process arguments
91
await run();
92

93
// For custom CLI tools
94
import { spawn } from "child_process";
95

96
const child = spawn("node", ["-e", `
97
  const { run } = require("@wdio/cli");
98
  run();
99
`], {
100
  stdio: "inherit",
101
  env: { ...process.env, NODE_ENV: "test" }
102
});
103
```
104

105
### OnCompleteResult Interface
106

107
Test result aggregation interface for reporting test outcomes.
108

109
```typescript { .api }
110
interface OnCompleteResult {
111
  finished: number;
112
  passed: number;
113
  retries: number;
114
  failed: number;
115
}
116
```
117

118
### Watcher Class
119

120
File watching system for continuous test execution during development with intelligent change detection.
121

122
```typescript { .api }
123
/**
124
 * File watcher for watch mode test execution
125
 */
126
class Watcher {
127
  /**
128
   * Initialize watcher with configuration
129
   * @param configFile - Path to configuration file
130
   * @param args - Command arguments excluding configPath
131
   */
132
  constructor(
133
    configFile: string,
134
    args: Omit<RunCommandArguments, 'configPath'>
135
  );
136

137
  /**
138
   * Start watching files for changes
139
   * @returns Promise that resolves when watcher is stopped
140
   */
141
  watch(): Promise<void>;
142
}
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { Watcher } from "@wdio/cli";
149

150
// Start watching for changes
151
const watcher = new Watcher("./wdio.conf.js", {
152
  spec: ["./test/specs/**/*.js"],
153
  logLevel: "info"
154
});
155

156
await watcher.watch();
157

158
// Custom watch setup
159
const watcher = new Watcher("./wdio.conf.js", {
160
  suite: ["unit", "integration"],
161
  bail: 1
162
});
163

164
await watcher.watch();
165
```
166

167
## Utility Functions
168

169
### Hook Execution
170

171
```typescript { .api }
172
/**
173
 * Execute service hooks with error handling
174
 */
175
function runServiceHook(
176
  launcher: Services.ServiceInstance[],
177
  hookName: keyof Services.HookFunctions,
178
  ...args: unknown[]
179
): Promise<HookError[]>;
180

181
/**
182
 * Execute launcher hooks
183
 */
184
function runLauncherHook(
185
  config: Options.Testrunner,
186
  hookName: string,
187
  ...args: unknown[]
188
): Promise<void>;
189

190
/**
191
 * Execute onComplete hooks with result aggregation
192
 */
193
function runOnCompleteHook(
194
  config: Options.Testrunner,
195
  results: OnCompleteResult,
196
  capabilities: Capabilities.DesiredCapabilities
197
): Promise<void>;
198
```
199

200
### Configuration Utilities
201

202
```typescript { .api }
203
/**
204
 * Get and validate capabilities configuration
205
 */
206
function getCapabilities(
207
  config: Options.Testrunner
208
): Capabilities.DesiredCapabilities[];
209

210
/**
211
 * Coerce command-line options to proper types
212
 */
213
function coerceOptsFor(
214
  options: Record<string, any>
215
): Record<string, any>;
216

217
/**
218
 * Get Node.js version information
219
 */
220
function nodeVersion(): {
221
  major: number;
222
  minor: number;
223
  patch: number;
224
  version: string;
225
};
226
```
227

228
## Error Handling
229

230
### Types
231

232
```typescript { .api }
233
interface HookError {
234
  origin: string;
235
  message: string;
236
}
237
```
238

239
## Integration Patterns
240

241
### CI/CD Integration
242

243
```typescript
244
import { Launcher } from "@wdio/cli";
245

246
// CI pipeline integration
247
async function runTestsInCI() {
248
  const launcher = new Launcher("./wdio.ci.conf.js", {
249
    logLevel: "warn",
250
    bail: 1,
251
    reporters: [["spec"], ["junit", { outputDir: "./test-results" }]]
252
  });
253

254
  const exitCode = await launcher.run();
255
  
256
  if (exitCode !== 0) {
257
    console.error("Tests failed in CI");
258
    process.exit(exitCode);
259
  }
260
  
261
  console.log("All tests passed in CI");
262
}
263
```
264

265
### Custom Test Runner
266

267
```typescript
268
import { Launcher } from "@wdio/cli";
269

270
class CustomTestRunner {
271
  private launcher: Launcher;
272

273
  constructor(configPath: string) {
274
    this.launcher = new Launcher(configPath);
275
  }
276

277
  async runTests(): Promise<number> {
278
    const exitCode = await this.launcher.run();
279
    
280
    if (exitCode === 0) {
281
      console.log("All tests passed!");
282
    } else {
283
      console.error(`Tests failed with exit code: ${exitCode}`);
284
    }
285
    
286
    return exitCode;
287
  }
288
}
289
```