Implementation:Webdriverio Webdriverio DriverManager

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

Overview

Orchestrates browser driver and browser binary setup for all capabilities before test execution begins, routing each browser type to its appropriate installation function.

Description

The DriverManager module provides setupDriver and setupBrowser as high-level orchestration functions that process the full set of test runner capabilities. An internal mapCapabilities helper normalizes the capabilities structure (handling arrays, W3C format, multiremote configurations) to extract individual browser capabilities, then filters out capabilities that do not require local driver setup (remote drivers, Safari, capabilities with explicit binary paths, or environment-provided paths). It groups capabilities by browser name and version to avoid redundant downloads, then runs the appropriate setup function for each unique browser/version combination in parallel using Promise.all. setupDriver delegates to setupChromedriver, setupGeckodriver, or setupEdgedriver based on the browser name. setupBrowser delegates to setupPuppeteerBrowser for Chrome and Firefox binary installation. The module defines a BrowserDriverTaskLabel enum to label log messages for browser binaries versus browser drivers.

Usage

Use setupDriver and setupBrowser in the test runner's preparation phase (before any sessions are created) to ensure all required browser binaries and drivers are downloaded and available. These functions are typically called by the WebdriverIO launcher during the onPrepare lifecycle phase.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-utils/src/node/manager.ts
Lines: 1-145

Signature

export async function setupDriver(
    options: Omit<Options.WebDriver, 'capabilities'>,
    caps: Capabilities.TestrunnerCapabilities
): Promise<void>

export function setupBrowser(
    options: Omit<Options.WebDriver, 'capabilities'>,
    caps: Capabilities.TestrunnerCapabilities
): Promise<void>

enum BrowserDriverTaskLabel {
    BROWSER = 'browser binaries',
    DRIVER = 'browser driver'
}

Import

import { setupDriver, setupBrowser } from '@wdio/utils/node/manager'

I/O Contract

Inputs

Name	Type	Required	Description
options	Omit<Options.WebDriver, 'capabilities'>	Yes	WebDriver options including cacheDir, protocol, hostname, port, path, user, and key. Used to determine if a remote driver is configured (in which case setup is skipped).
caps	Capabilities.TestrunnerCapabilities	Yes	The full testrunner capabilities, which can be an array of W3C capabilities, multiremote capabilities, or mixed configurations. Each capability is inspected for browserName and browserVersion.

Outputs

Name	Type	Description
setupDriver result	Promise<void>	Resolves when all required browser drivers have been downloaded and installed. Rejects if any driver setup fails.
setupBrowser result	Promise<void>	Resolves when all required browser binaries have been downloaded and installed. Rejects if any browser setup fails.

Usage Examples

import { setupDriver, setupBrowser } from '@wdio/utils/node/manager'

const options = {
    cacheDir: '/tmp/wdio-cache',
    protocol: 'http',
    hostname: 'localhost',
    path: '/'
}

const capabilities = [
    { browserName: 'chrome', browserVersion: '120' },
    { browserName: 'firefox' },
    { browserName: 'chrome', browserVersion: '119' }
]

// Download browser binaries (Chrome, Firefox)
await setupBrowser(options, capabilities)

// Download matching drivers (Chromedriver v120, Chromedriver v119, Geckodriver)
await setupDriver(options, capabilities)

// Multiremote capabilities are also supported
const multiremoteCaps = {
    browserA: {
        capabilities: { browserName: 'chrome' }
    },
    browserB: {
        capabilities: { browserName: 'firefox' }
    }
}
await setupDriver(options, multiremoteCaps)
await setupBrowser(options, multiremoteCaps)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment