WebdriverIO CLI (@wdio/cli)

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.

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

Package Information

• Package Name: @wdio/cli
• Package Type: npm
• Language: TypeScript
• Installation: npm install @wdio/cli
• Node.js: >= 18.20.0

Core Imports

import { Launcher, run } from "@wdio/cli";

For CommonJS:

const { Launcher, run } = require("@wdio/cli");

Basic Usage

CLI Usage

# Run tests with default configuration
wdio wdio.conf.js

# Run tests with explicit run command
wdio run wdio.conf.js

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

# Run in watch mode
wdio run wdio.conf.js --watch

# Start REPL session
wdio repl chrome

Programmatic Usage

import { Launcher } from "@wdio/cli";

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

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

Architecture

WebdriverIO CLI is built around several key components:

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

Capabilities

CLI Commands

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.

// CLI binary entry point
wdio [command] [options]

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

CLI Commands

Programmatic API

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.

class Launcher {
  constructor(configFilePath: string, args?: RunCommandArguments, isWatchMode?: boolean);
  run(): Promise<undefined | number>;
}

function run(): Promise<false | void>;

Programmatic API

Configuration Options

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

interface RunCommandArguments {
  configPath: string;
  watch?: boolean;
  hostname?: string;
  port?: number;
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
  // ... extensive configuration options
}

Configuration

Watch Mode

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.

class Watcher {
  constructor(configFile: string, args: Omit<RunCommandArguments, 'configPath'>);
  watch(): Promise<void>;
}

Watch Mode