tessl/npm-wdio--cli

WebdriverIO testrunner command line interface for test automation

—

Pending

Overview

Eval results

Files

Configuration

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

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

Capabilities

Run Command Arguments

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

interface RunCommandArguments {
  /** Path to WebdriverIO configuration file */
  configPath: string;
  
  /** Enable watch mode for continuous testing */
  watch?: boolean;
  
  /** WebDriver server hostname */
  hostname?: string;
  
  /** WebDriver server port */
  port?: number;
  
  /** Path to WebDriver endpoints (default "/") */
  path?: string;
  
  /** Username for cloud service authentication */
  user?: string;
  
  /** Access key for cloud service authentication */
  key?: string;
  
  /** Logging verbosity level */
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
  
  /** Stop test execution after N failures */
  bail?: number;
  
  /** Base URL for test execution */
  baseUrl?: string;
  
  /** Shard configuration for parallel execution */
  shard?: Options.ShardOptions;
  
  /** Default wait timeout in milliseconds */
  waitforTimeout?: number;
  
  /** Test framework to use */
  framework?: string;
  
  /** Reporter configuration */
  reporters?: Reporters.ReporterEntry[];
  
  /** Test suites to execute */
  suite?: string[];
  
  /** Specific spec files to run */
  spec?: string[];
  
  /** Patterns to exclude from execution */
  exclude?: string[];
  
  /** Mocha framework options */
  mochaOpts?: WebdriverIO.MochaOpts;
  
  /** Jasmine framework options */
  jasmineOpts?: WebdriverIO.JasmineOpts;
  
  /** Cucumber framework options */
  cucumberOpts?: WebdriverIO.CucumberOpts;
  
  /** Enable code coverage collection */
  coverage?: boolean;
  
  /** Visual regression snapshot update mode */
  updateSnapshots?: Options.Testrunner['updateSnapshots'];
  
  /** TypeScript configuration file path */
  tsConfigPath?: string;
  
  /** Repeat specific specs and/or suites N times */
  repeat?: number;
  
  /** Internal: Services to ignore in workers */
  ignoredWorkerServices?: string[];
}

REPL Command Arguments

Configuration for interactive WebDriver REPL sessions.

interface ReplCommandArguments {
  /** Mobile platform version */
  platformVersion: string;
  
  /** Mobile device name */
  deviceName: string;
  
  /** Device unique identifier */
  udid: string;
  
  /** Browser or device option */
  option: string;
  
  /** WebDriver capabilities (JSON string or file path) */
  capabilities: string;
}

Install Command Arguments

Configuration for WebdriverIO plugin installation.

interface InstallCommandArguments {
  /** Configuration file path */
  config?: string;
  
  /** Type of package to install */
  type: 'service' | 'reporter' | 'framework' | 'plugin';
  
  /** Package name (without @wdio/ prefix) */
  name: string;
}

Project Properties

Project metadata and configuration detection.

interface ProjectProps {
  /** ESM module support detection */
  esmSupported: boolean;
  
  /** Project root path */
  path: string;
  
  /** Parsed package.json data */
  packageJson: NormalizedPackageJson;
}

/** Package information for supported WebdriverIO packages */
interface SupportedPackage {
  /** Full package name */
  package: string;
  
  /** Short name for CLI usage */
  short: string;
  
  /** Description of package purpose */
  purpose: string;
}

Configuration Examples

Basic Test Execution

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

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

// With basic options
const launcher = new Launcher("./wdio.conf.js", {
  logLevel: "info",
  bail: 1
});

Environment-Specific Configuration

// Development environment
const devLauncher = new Launcher("./wdio.conf.js", {
  baseUrl: "http://localhost:3000",
  logLevel: "debug",
  watch: true,
  spec: ["./test/specs/unit/**/*.js"]
});

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

// Production environment
const prodLauncher = new Launcher("./wdio.conf.js", {
  baseUrl: "https://example.com",
  logLevel: "warn",
  bail: 1,
  reporters: [["spec"], ["junit", { outputDir: "./test-results" }]]
});

Cloud Service Configuration

// Sauce Labs configuration
const sauceLauncher = new Launcher("./wdio.conf.js", {
  user: process.env.SAUCE_USERNAME,
  key: process.env.SAUCE_ACCESS_KEY,
  hostname: "ondemand.saucelabs.com",
  port: 443,
  path: "/wd/hub"
});

// BrowserStack configuration
const browserStackLauncher = new Launcher("./wdio.conf.js", {
  user: process.env.BROWSERSTACK_USERNAME,
  key: process.env.BROWSERSTACK_ACCESS_KEY,
  hostname: "hub-cloud.browserstack.com",
  port: 443
});

Framework-Specific Configuration

// Mocha framework
const mochaLauncher = new Launcher("./wdio.conf.js", {
  framework: "mocha",
  mochaOpts: {
    timeout: 60000,
    retries: 2,
    grep: "critical"
  }
});

// Jasmine framework
const jasmineLauncher = new Launcher("./wdio.conf.js", {
  framework: "jasmine",
  jasmineOpts: {
    defaultTimeoutInterval: 60000,
    stopSpecOnExpectationFailure: false,
    random: true
  }
});

// Cucumber framework
const cucumberLauncher = new Launcher("./wdio.conf.js", {
  framework: "cucumber",
  cucumberOpts: {
    timeout: 60000,
    strict: false,
    tags: "@smoke or @regression",
    require: ["./test/step-definitions/**/*.js"]
  }
});

Advanced Configuration

// Parallel execution with sharding
const shardedLauncher = new Launcher("./wdio.conf.js", {
  shard: {
    current: 1,
    total: 4
  },
  spec: ["./test/specs/**/*.js"],
  maxInstances: 5
});

// Coverage collection
const coverageLauncher = new Launcher("./wdio.conf.js", {
  coverage: true,
  reporters: [
    ["spec"],
    ["coverage", { 
      dir: "./coverage",
      reports: ["html", "lcov", "text"]
    }]
  ]
});

// Custom TypeScript configuration
const tsLauncher = new Launcher("./wdio.conf.js", {
  tsConfigPath: "./tsconfig.test.json",
  spec: ["./test/specs/**/*.ts"]
});

Environment Variables

Standard Environment Variables

// Authentication
process.env.WDIO_USER = "username";
process.env.WDIO_KEY = "accesskey";

// Server configuration
process.env.WDIO_HOSTNAME = "selenium-server.com";
process.env.WDIO_PORT = "4444";
process.env.WDIO_PATH = "/wd/hub";

// Logging
process.env.WDIO_LOG_LEVEL = "debug";

// Base URL
process.env.WDIO_BASE_URL = "https://example.com";

Cloud Service Environment Variables

// Sauce Labs
process.env.SAUCE_USERNAME = "your-username";
process.env.SAUCE_ACCESS_KEY = "your-access-key";

// BrowserStack
process.env.BROWSERSTACK_USERNAME = "your-username";
process.env.BROWSERSTACK_ACCESS_KEY = "your-access-key";

// TestingBot
process.env.TB_KEY = "your-key";
process.env.TB_SECRET = "your-secret";

// LambdaTest
process.env.LT_USERNAME = "your-username";
process.env.LT_ACCESS_KEY = "your-access-key";

Configuration Validation

Type Safety

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

// Type-safe configuration function
function createTestConfig(
  baseConfig: Partial<RunCommandArguments>
): RunCommandArguments {
  return {
    configPath: "./wdio.conf.js",
    logLevel: "info",
    bail: 0,
    ...baseConfig
  };
}

// Usage with validation
const config = createTestConfig({
  baseUrl: "https://example.com",
  suite: ["smoke"],
  logLevel: "debug" // TypeScript ensures valid log level
});

Runtime Validation

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

// Validate and coerce CLI options
const validatedOptions = coerceOptsFor({
  bail: "3",        // Coerced to number
  watch: "true",    // Coerced to boolean
  logLevel: "info", // Validated against allowed values
  spec: "test.js"   // Coerced to array
});

Constants

Default Configurations

/** Android device default configuration */
const ANDROID_CONFIG = {
  platformName: 'Android',
  automationName: 'UiAutomator2',
  deviceName: 'Test'
};

/** iOS device default configuration */
const IOS_CONFIG = {
  platformName: 'iOS',
  automationName: 'XCUITest',
  deviceName: 'iPhone Simulator'
};

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

/** Package metadata */
const pkg = {
  name: '@wdio/cli',
  version: '9.19.2',
  description: 'WebdriverIO testrunner command line interface'
  // ... additional package.json fields
};

Testrunner Defaults

/** Default testrunner configuration schema with validation */
const TESTRUNNER_DEFAULTS: Options.Definition<Options.Testrunner & { capabilities: unknown }> = {
  specs: {
    type: 'object',
    validate: (param: string[]) => {
      if (!Array.isArray(param)) {
        throw new Error('the "specs" option needs to be a list of strings');
      }
    }
  },
  exclude: {
    type: 'object',
    validate: (param: string[]) => {
      if (!Array.isArray(param)) {
        throw new Error('the "exclude" option needs to be a list of strings');
      }
    }
  },
  bail: {
    type: 'number',
    default: 0
  },
  // ... extensive configuration schema
};

Install with Tessl CLI