Principle:SeleniumHQ Selenium Browser Options Configuration
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, WebDriver, Configuration |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for declaring browser-specific preferences and capabilities that configure the WebDriver session according to the W3C WebDriver specification.
Description
Browser Options Configuration is the process of defining the desired state of a browser session before it is created. In the W3C WebDriver protocol, capabilities are the primary mechanism for this: they are key-value pairs that describe what the client wants from the session (desired capabilities) and what the server actually provides (matched capabilities). Each browser vendor extends the base W3C capabilities with vendor-specific options (e.g., goog:chromeOptions for Chrome, moz:firefoxOptions for Firefox). This principle addresses how to construct these capability objects programmatically, covering arguments, extensions, binary paths, proxy settings, and page load strategies.
Usage
Apply this principle at the very start of any WebDriver automation workflow, before creating a session. It is essential when:
- Running browsers in headless mode for CI pipelines
- Loading extensions for test scenarios
- Setting proxy configurations for network testing
- Targeting a specific browser binary or version
- Configuring page load strategy (normal, eager, none)
Theoretical Basis
The W3C WebDriver specification defines capabilities as a JSON object sent in the POST /session request body. The capability matching algorithm proceeds as:
# Pseudocode: W3C Capability Processing
1. Client constructs "alwaysMatch" capabilities (required)
2. Client optionally provides "firstMatch" array (alternatives)
3. Server validates all keys against W3C standard names
4. Server merges alwaysMatch with each firstMatch candidate
5. First successful match creates the session
Vendor-specific extensions use a prefix (e.g., goog:, moz:, ms:) to avoid conflicts with standard W3C capability keys.