tessl/npm-wdio--cli

WebdriverIO testrunner command line interface for test automation

—

Pending

Overview

Eval results

Files

Programmatic API

Name: tessl/npm-wdio--cli
Author: tessl

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

Capabilities

Launcher Class

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

/**
 * Main test launcher class for programmatic test execution
 */
class Launcher {
  /**
   * Initialize launcher with configuration and options
   * @param configFilePath - Path to WebdriverIO configuration file
   * @param args - Additional command-line arguments and options
   * @param isWatchMode - Enable watch mode for continuous testing
   */
  constructor(
    configFilePath: string, 
    args?: RunCommandArguments, 
    isWatchMode?: boolean
  );

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

  // Properties
  readonly configParser: ConfigParser;
  readonly isMultiremote: boolean;
  readonly isParallelMultiremote: boolean;
  readonly runner?: Services.RunnerInstance;
  readonly interface?: CLInterface;
}

Usage Examples:

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

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

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

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

// Watch mode for development
const launcher = new Launcher("./wdio.conf.js", {
  watch: true,
  spec: ["./test/specs/**/*.js"]
}, true);

Run Function

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

/**
 * Main CLI entry point function
 * Processes command-line arguments and executes commands
 * @returns Promise resolving to false on error, void on success
 */
function run(): Promise<false | void>;

Usage Examples:

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

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

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

const child = spawn("node", ["-e", `
  const { run } = require("@wdio/cli");
  run();
`], {
  stdio: "inherit",
  env: { ...process.env, NODE_ENV: "test" }
});

OnCompleteResult Interface

Test result aggregation interface for reporting test outcomes.

interface OnCompleteResult {
  finished: number;
  passed: number;
  retries: number;
  failed: number;
}

Watcher Class

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

/**
 * File watcher for watch mode test execution
 */
class Watcher {
  /**
   * Initialize watcher with configuration
   * @param configFile - Path to configuration file
   * @param args - Command arguments excluding configPath
   */
  constructor(
    configFile: string,
    args: Omit<RunCommandArguments, 'configPath'>
  );

  /**
   * Start watching files for changes
   * @returns Promise that resolves when watcher is stopped
   */
  watch(): Promise<void>;
}

Usage Examples:

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

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

await watcher.watch();

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

await watcher.watch();

Utility Functions

Hook Execution

/**
 * Execute service hooks with error handling
 */
function runServiceHook(
  launcher: Services.ServiceInstance[],
  hookName: keyof Services.HookFunctions,
  ...args: unknown[]
): Promise<HookError[]>;

/**
 * Execute launcher hooks
 */
function runLauncherHook(
  config: Options.Testrunner,
  hookName: string,
  ...args: unknown[]
): Promise<void>;

/**
 * Execute onComplete hooks with result aggregation
 */
function runOnCompleteHook(
  config: Options.Testrunner,
  results: OnCompleteResult,
  capabilities: Capabilities.DesiredCapabilities
): Promise<void>;

Configuration Utilities

/**
 * Get and validate capabilities configuration
 */
function getCapabilities(
  config: Options.Testrunner
): Capabilities.DesiredCapabilities[];

/**
 * Coerce command-line options to proper types
 */
function coerceOptsFor(
  options: Record<string, any>
): Record<string, any>;

/**
 * Get Node.js version information
 */
function nodeVersion(): {
  major: number;
  minor: number;
  patch: number;
  version: string;
};

Error Handling

Types

interface HookError {
  origin: string;
  message: string;
}

Integration Patterns

CI/CD Integration

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

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

  const exitCode = await launcher.run();
  
  if (exitCode !== 0) {
    console.error("Tests failed in CI");
    process.exit(exitCode);
  }
  
  console.log("All tests passed in CI");
}

Custom Test Runner

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

class CustomTestRunner {
  private launcher: Launcher;

  constructor(configPath: string) {
    this.launcher = new Launcher(configPath);
  }

  async runTests(): Promise<number> {
    const exitCode = await this.launcher.run();
    
    if (exitCode === 0) {
      console.log("All tests passed!");
    } else {
      console.error(`Tests failed with exit code: ${exitCode}`);
    }
    
    return exitCode;
  }
}

Install with Tessl CLI