Environment:Webdriverio Webdriverio Browser Driver Environment
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Browser_Automation |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Browser and WebDriver binary requirements for local test execution, including automatic driver management via `@puppeteer/browsers`.
Description
WebdriverIO v9 automatically manages browser driver downloads through the `@wdio/utils` package, which uses `@puppeteer/browsers` (^2.2.0) for binary management. Supported browsers include Chrome/Chromium (via chromedriver), Firefox (via geckodriver ^6.1.0), Microsoft Edge (via edgedriver ^6.1.2), and Safari (via safaridriver ^1.0.0). Driver binaries are cached in a configurable directory (defaulting to `os.tmpdir()`) and matched to installed browser versions automatically. The driver setup can be skipped for cloud sessions or when custom binary paths are provided.
Usage
Use this environment for local test execution against real browsers. This is the mandatory prerequisite for the Remote_Function and Url_Dollar_DollarDollar_Commands implementations when running locally (not via cloud services). Skip this environment when using BrowserStack, Sauce Labs, or other cloud providers.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, or Windows | Safari only on macOS |
| Hardware | Standard desktop | No GPU required for headless mode |
| Disk | 200MB+ per browser | Cached driver binaries in temp directory |
| Network | Internet (first run) | To download driver binaries; cached afterward |
Dependencies
System Packages
At least one browser must be installed:
- Google Chrome / Chromium (any recent version)
- Mozilla Firefox (any recent version)
- Microsoft Edge (any recent version)
- Safari (macOS only, pre-installed)
For headless Linux testing:
- `xvfb` (X Virtual Framebuffer) — required when no display server is available
Language Packages
Automatic (managed by WebdriverIO):
- `@puppeteer/browsers` ^2.2.0 — browser binary management
- `geckodriver` ^6.1.0 — Firefox WebDriver
- `edgedriver` ^6.1.2 — Edge WebDriver
- `safaridriver` ^1.0.0 — Safari WebDriver
Optional:
- `puppeteer-core` >= 22.x — for Chrome DevTools Protocol features
- `@wdio/xvfb` — automated XVFB management for headless Linux
Credentials
- `CHROMEDRIVER_PATH`: (Optional) Custom path to a pre-installed chromedriver binary. Skips automatic download.
- `WEBDRIVER_CACHE_DIR`: (Optional) Custom path for caching downloaded driver binaries. Defaults to `os.tmpdir()`.
- `WDIO_SKIP_DRIVER_SETUP`: (Optional) Set to any value to skip automatic driver download entirely.
Quick Install
# WebdriverIO handles driver setup automatically
# Just install WebdriverIO and run — drivers download on first use
npm install webdriverio @wdio/cli
# To use a custom chromedriver
export CHROMEDRIVER_PATH="/usr/local/bin/chromedriver"
# To skip automatic driver setup (e.g., in CI with pre-installed drivers)
export WDIO_SKIP_DRIVER_SETUP=1
# For headless Linux (Ubuntu/Debian)
sudo apt-get install xvfb
Code Evidence
Driver skip conditions from `packages/wdio-utils/src/driver/`:
// Skip driver setup if env var is set
if (process.env.WDIO_SKIP_DRIVER_SETUP) {
return
}
// Skip if running cloud session (remote hostname/port defined)
// Skip if custom binary path defined in capabilities
// Skip if CHROMEDRIVER_PATH env var is set for Chrome
Cache directory configuration:
const cacheDir = process.env.WEBDRIVER_CACHE_DIR || os.tmpdir()
Browser capability keys for driver options:
// Chrome: 'goog:chromeOptions'
// Firefox: 'moz:firefoxOptions'
// Edge: 'ms:edgeOptions'
// Safari: 'wdio:safaridriverOptions'
Dynamic port allocation for drivers:
// Uses get-port package for dynamic port allocation
// wait-port timeout: 10 seconds for driver startup
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `Failed to download browser driver` | Network error or firewall | Check internet access; set `WEBDRIVER_CACHE_DIR` to writable path |
| `ChromeDriver version mismatch` | Chrome updated but cached driver is old | Delete cache directory or set `WDIO_SKIP_DRIVER_SETUP=1` with manual driver |
| `directory already in use` | Chrome parallel workers share user-data-dir (Windows) | WebdriverIO auto-generates unique dirs per worker |
| `Xvfb is not installed` | Missing display server on Linux | Install xvfb: `sudo apt-get install xvfb` |
Compatibility Notes
- Chrome/Chromium: Driver version auto-matched to installed browser. Custom binary via `wdio:chromedriverOptions.binary` capability.
- Firefox: Managed via geckodriver. Supports stable and latest channels.
- Edge: Chromium-based, uses similar flags to Chrome. Managed via edgedriver.
- Safari: Uses system-installed SafariDriver (macOS only). No automatic download needed. Enable via `safaridriver --enable` (requires admin).
- XVFB: The `@wdio/xvfb` package can auto-install xvfb but requires root/sudo privileges. Manual install recommended for CI.
- Headless Mode: Chrome uses `--headless` flag via `goog:chromeOptions`; Firefox uses `--headless` or `-headless` via `moz:firefoxOptions`.