0
# WebdriverIO CLI (@wdio/cli)
1

2
WebdriverIO CLI is a comprehensive command-line interface and programmatic API for the WebdriverIO test automation framework. It provides both CLI commands for test execution and a programmatic API for integrating WebdriverIO into custom workflows, supporting end-to-end, unit, and component testing across browsers and mobile platforms.
3

4
This package primarily exports the `Launcher` class for programmatic test execution, the `run` function for CLI execution, and various TypeScript interfaces for configuration.
5

6
## Package Information
7

8
- **Package Name**: @wdio/cli
9
- **Package Type**: npm
10
- **Language**: TypeScript
11
- **Installation**: `npm install @wdio/cli`
12
- **Node.js**: >= 18.20.0
13

14
## Core Imports
15

16
```typescript
17
import { Launcher, run } from "@wdio/cli";
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { Launcher, run } = require("@wdio/cli");
24
```
25

26
## Basic Usage
27

28
### CLI Usage
29

30
```bash
31
# Run tests with default configuration
32
wdio wdio.conf.js
33

34
# Run tests with explicit run command
35
wdio run wdio.conf.js
36

37
# Run specific test suite
38
wdio run wdio.conf.js --suite regression
39

40
# Run in watch mode
41
wdio run wdio.conf.js --watch
42

43
# Start REPL session
44
wdio repl chrome
45
```
46

47
### Programmatic Usage
48

49
```typescript
50
import { Launcher } from "@wdio/cli";
51

52
// Initialize launcher with configuration
53
const launcher = new Launcher("./wdio.conf.js", {
54
  spec: ["./test/specs/**/*.js"],
55
  logLevel: "info"
56
});
57

58
// Run tests programmatically
59
const exitCode = await launcher.run();
60
console.log(`Tests completed with exit code: ${exitCode}`);
61
```
62

63
## Architecture
64

65
WebdriverIO CLI is built around several key components:
66

67
- **CLI Interface**: Command-line tool with multiple commands (run, repl, config, install)
68
- **Launcher Class**: Programmatic test orchestration with multi-worker support
69
- **Configuration System**: Comprehensive configuration parsing and validation
70
- **Watch Mode**: File watching for continuous test execution during development
71
- **Service Integration**: Hook system for integrating with external services and reporters
72
- **Multi-remote Support**: Parallel execution across multiple browser sessions
73

74
## Capabilities
75

76
### CLI Commands
77

78
Complete command-line interface for WebdriverIO test execution, configuration, and project setup. Includes commands for running tests, interactive REPL sessions, configuration wizards, and plugin installation.
79

80
```typescript { .api }
81
// CLI binary entry point
82
wdio [command] [options]
83

84
// Available commands:
85
// - run <configPath>: Execute test suite (default)
86
// - repl <option> [capabilities]: Interactive WebDriver session
87
// - config: Configuration wizard
88
// - install <type> <name>: Install WebdriverIO plugins
89
```
90

91
[CLI Commands](./cli-commands.md)
92

93
### Programmatic API
94

95
Programmatic interface for integrating WebdriverIO test execution into custom applications and CI/CD pipelines. Provides full control over test orchestration with event handling and result reporting.
96

97
```typescript { .api }
98
class Launcher {
99
  constructor(configFilePath: string, args?: RunCommandArguments, isWatchMode?: boolean);
100
  run(): Promise<undefined | number>;
101
}
102

103
function run(): Promise<false | void>;
104
```
105

106
[Programmatic API](./programmatic-api.md)
107

108
### Configuration Options
109

110
Comprehensive configuration system supporting all WebdriverIO testing scenarios including multi-browser testing, cloud service integration, and custom test frameworks.
111

112
```typescript { .api }
113
interface RunCommandArguments {
114
  configPath: string;
115
  watch?: boolean;
116
  hostname?: string;
117
  port?: number;
118
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
119
  // ... extensive configuration options
120
}
121
```
122

123
[Configuration](./configuration.md)
124

125
### Watch Mode
126

127
Intelligent file watching system for continuous test execution during development. Automatically detects changes in test files and configuration, running only affected tests for optimal development workflow.
128

129
```typescript { .api }
130
class Watcher {
131
  constructor(configFile: string, args: Omit<RunCommandArguments, 'configPath'>);
132
  watch(): Promise<void>;
133
}
134
```
135

136
[Watch Mode](./watch-mode.md)