Implementation:Webdriverio Webdriverio StartWebDriver

Knowledge Sources	Webdriverio_Webdriverio
Domains	Driver_Management, Process_Management
Last Updated	2026-02-12 00:00 GMT

Overview

Starts the appropriate browser driver process (Chromedriver, Geckodriver, Safaridriver, or Edgedriver) with automatic port allocation, binary resolution, and log management.

Description

The startWebDriver function is the main entry point for launching a local browser driver process before creating a WebDriver session. It first checks for Appium capabilities (returning early for mobile sessions) and validates that a browserName is defined. It allocates a free port using get-port, then branches based on the browser name. For Chrome, it calls setupPuppeteerBrowser to locate or download the browser binary, setupChromedriver to locate or download the matching driver, merges goog:chromeOptions with the resolved binary path and default preferences (disabling password leak detection), adds unique user data directories on Windows for parallel workers, parses driver options into CLI arguments, and spawns the Chromedriver process with NODE_OPTIONS cleared to avoid Electron conflicts. For Firefox, it sets up the browser binary via setupPuppeteerBrowser, configures moz:firefoxOptions, and starts Geckodriver. For Safari, it starts Safaridriver with technology preview detection. For Edge, it starts Edgedriver with fallback retry logic and auto-detects the Edge binary path on Linux. After spawning, it pipes stdout/stderr to either a log file (if outputDir is set) or to the logger, waits for the port to become available (10-second timeout, 100ms retry interval), and sets options.hostname and options.port to the allocated values.

Usage

Use startWebDriver when running WebdriverIO in standalone or testrunner mode with local browser sessions. It is called automatically by the framework when no remote driver connection is configured. The returned ChildProcess can be used to manage the driver lifecycle (e.g., killing it after tests complete).

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-utils/src/node/startWebDriver.ts
Lines: 1-215

Signature

export async function startWebDriver(
    options: Capabilities.RemoteConfig
): Promise<ChildProcess | undefined>

Import

import { startWebDriver } from '@wdio/utils'

I/O Contract

Inputs

Name	Type	Required	Description
options	Capabilities.RemoteConfig	Yes	Configuration object containing capabilities (W3C or plain), outputDir for log files, and connection properties (hostname, port) that will be mutated to reflect the started driver.
options.capabilities	WebdriverIO.Capabilities or W3CCapabilities	Yes	Must include browserName. May include vendor-specific options like goog:chromeOptions, moz:firefoxOptions, ms:edgeOptions, wdio:chromedriverOptions, wdio:geckodriverOptions, wdio:edgedriverOptions, or wdio:safaridriverOptions.
options.outputDir	string	No	If set, driver stdout/stderr is written to a log file in this directory instead of being piped to the logger.

Outputs

Name	Type	Description
return value	Promise<ChildProcess or undefined>	The spawned driver child process, or undefined if the session is a mobile/Appium session or unit test mode is active.
options.hostname (mutated)	string	Set to "localhost" after the driver starts.
options.port (mutated)	number	Set to the allocated port number after the driver starts.

Usage Examples

import { startWebDriver } from '@wdio/utils'

// Start a Chrome driver
const options = {
    capabilities: {
        browserName: 'chrome',
        'goog:chromeOptions': {
            args: ['--headless']
        }
    },
    outputDir: './logs'
}

const driverProcess = await startWebDriver(options)
console.log(`Driver running on ${options.hostname}:${options.port}`)

// Create a WebDriver session using the allocated port
// ... session creation logic ...

// Clean up when done
if (driverProcess) {
    driverProcess.kill()
}

// Start a Firefox driver with custom Geckodriver options
const firefoxOptions = {
    capabilities: {
        browserName: 'firefox',
        'wdio:geckodriverOptions': {
            binary: '/usr/local/bin/geckodriver'
        }
    }
}
const geckoProcess = await startWebDriver(firefoxOptions)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment