Implementation:Webdriverio Webdriverio Node Utils

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

Overview

Provides browser driver download, installation, and configuration utilities for Chrome, Firefox, and Edge within the Node.js environment.

Description

The Node Utils module contains functions for managing browser binaries and their corresponding drivers. setupPuppeteerBrowser downloads or locates Chrome/Chromium/Firefox browser binaries using the @puppeteer/browsers package, returning the executable path and resolved browser version. setupChromedriver, setupGeckodriver, and setupEdgedriver handle downloading the matching driver versions. Helper functions getBuildIdByChromePath and getBuildIdByFirefoxPath extract version strings from installed browser binaries by executing them with version flags or reading filesystem metadata on Windows. The canAccess utility checks file accessibility, parseParams converts option objects into CLI argument arrays for driver processes, and getDriverOptions extracts vendor-specific driver options from capabilities.

Usage

Use these utilities when WebdriverIO needs to automatically manage browser and driver installations. They are called by the driver manager and startWebDriver modules to ensure the correct browser and driver binaries are available before starting a session. Direct usage is appropriate when building custom driver setup logic outside the standard test runner flow.

Code Reference

Source Location

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

Signature

export const canAccess: (file?: string) => boolean

export function parseParams(params: EdgedriverParameters): string[]

export function getBuildIdByChromePath(chromePath?: string): string | undefined

export async function getBuildIdByFirefoxPath(firefoxPath?: string): Promise<string | undefined>

export async function setupPuppeteerBrowser(
    cacheDir: string,
    caps: WebdriverIO.Capabilities
): Promise<{ executablePath: string; browserVersion: string }>

export function getDriverOptions(caps: WebdriverIO.Capabilities): Record<string, unknown>

export async function setupChromedriver(
    cacheDir: string,
    driverVersion?: string
): Promise<{ executablePath: string }>

export function setupGeckodriver(
    cacheDir: string,
    driverVersion?: string
): Promise<{ executablePath: string }>

export function setupEdgedriver(
    cacheDir: string,
    driverVersion?: string
): Promise<{ executablePath: string }>

Import

import { setupPuppeteerBrowser, setupChromedriver } from '@wdio/utils/node/utils'

I/O Contract

Inputs

Name	Type	Required	Description
cacheDir	string	Yes	Directory path for caching downloaded browser and driver binaries.
caps	WebdriverIO.Capabilities	Yes (setupPuppeteerBrowser)	Capabilities object containing browserName, browserVersion, and vendor-specific options.
driverVersion	string	No	Specific driver version to download; defaults to auto-detection from installed browser.
chromePath / firefoxPath	string	No	Path to an installed browser binary for version extraction.
file	string	No (canAccess)	File path to check accessibility for.
params	EdgedriverParameters	Yes (parseParams)	Object of driver parameters to convert to CLI argument strings.

Outputs

Name	Type	Description
executablePath	string	Absolute path to the downloaded or located browser/driver binary.
browserVersion	string	Resolved version string of the browser binary (e.g., "120.0.6099.71").
canAccess result	boolean	Whether the specified file exists and is accessible.
parseParams result	string[]	Array of CLI argument strings (e.g., ["--port=9515", "--allowed-origins=*"]).

Usage Examples

import { setupPuppeteerBrowser, setupChromedriver, canAccess } from '@wdio/utils/node/utils'
import os from 'node:os'

const cacheDir = os.tmpdir()

// Set up Chrome browser binary
const { executablePath, browserVersion } = await setupPuppeteerBrowser(cacheDir, {
    browserName: 'chrome'
})
console.log(`Chrome at: ${executablePath}, version: ${browserVersion}`)

// Set up matching Chromedriver
const driver = await setupChromedriver(cacheDir, browserVersion)
console.log(`Chromedriver at: ${driver.executablePath}`)

// Check if a binary exists
if (canAccess('/usr/bin/google-chrome')) {
    console.log('Chrome is installed system-wide')
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment