Implementation:SeleniumHQ Selenium ChromiumOptions Configuration

Knowledge Sources	Selenium ChromeDriver Options
Domains	Browser_Automation, WebDriver, Configuration
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for configuring Chromium-based browser sessions provided by the Selenium Java library.

Description

The ChromiumOptions class (and its subclasses ChromeOptions, EdgeOptions) provides a fluent API for constructing W3C-compliant browser capabilities. It extends AbstractDriverOptions and manages Chromium-specific settings including command-line arguments, extensions, experimental options, binary paths, and Android WebView configurations. ChromeOptions uses the vendor prefix goog:chromeOptions while EdgeOptions uses ms:edgeOptions. The class serializes extensions as Base64-encoded strings and assembles all options into an unmodifiable map under the vendor capability key.

Usage

Import and instantiate this class when you need to configure a Chromium-based browser session. Common scenarios include adding --headless mode, setting window size, loading packed CRX extensions, or pointing to a non-default browser binary.

Code Reference

Source Location

• Repository: Selenium
• File: java/src/org/openqa/selenium/chromium/ChromiumOptions.java
• Lines: L64-383
• Subclass: java/src/org/openqa/selenium/chrome/ChromeOptions.java (L48-71)

Signature

public class ChromiumOptions<T extends ChromiumOptions<?>>
    extends AbstractDriverOptions<ChromiumOptions<?>> {

    public ChromiumOptions(String capabilityType, String browserType, String capability);
    public T setBinary(File path);
    public T setBinary(String path);
    public T addArguments(String... arguments);
    public T addArguments(List<String> arguments);
    public T addExtensions(File... paths);
    public T addExtensions(List<File> paths);
    public T addEncodedExtensions(String... encoded);
    public T addEncodedExtensions(List<String> encoded);
    public T enableBiDi();
    public T setExperimentalOption(String name, Object value);
    public T setAndroidPackage(String androidPackage);
    public T setAndroidActivity(String activity);
    public T setAndroidDeviceSerialNumber(String serial);
    public T setUseRunningAndroidApp(boolean useIt);
    public T setAndroidProcess(String processName);
}

// ChromeOptions subclass
public class ChromeOptions extends ChromiumOptions<ChromeOptions> {
    public static final String CAPABILITY = "goog:chromeOptions";
    public static final String LOGGING_PREFS = "goog:loggingPrefs";
    public ChromeOptions();
    public ChromeOptions merge(Capabilities extraCapabilities);
}

Import

import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.chromium.ChromiumOptions;

I/O Contract

Inputs

Name	Type	Required	Description
arguments	String...	No	Command-line arguments (e.g., "--headless", "--window-size=1920,1080")
extensions	File...	No	Packed CRX extension files to load
binary	String or File	No	Path to a custom browser executable
experimentalOption	String name, Object value	No	Experimental Chromium options (e.g., "prefs", "excludeSwitches")
androidPackage	String	No	Android package name for WebView testing

Outputs

Name	Type	Description
Capabilities	Capabilities (Map)	W3C-compliant capability map including vendor-specific "goog:chromeOptions" with args, extensions, and binary

Usage Examples

Basic Chrome with Headless Mode

import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriver;

// 1. Create options
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless");
options.addArguments("--window-size=1920,1080");
options.addArguments("--disable-gpu");

// 2. Create driver with options
ChromeDriver driver = new ChromeDriver(options);

Chrome with Extensions and Custom Binary

import org.openqa.selenium.chrome.ChromeOptions;
import java.io.File;

ChromeOptions options = new ChromeOptions();
options.setBinary("/usr/bin/google-chrome-beta");
options.addExtensions(new File("/path/to/extension.crx"));
options.setExperimentalOption("excludeSwitches",
    List.of("enable-automation"));

ChromeDriver driver = new ChromeDriver(options);

Edge Options (Same API)

import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.edge.EdgeDriver;

EdgeOptions options = new EdgeOptions();
options.addArguments("--headless");
EdgeDriver driver = new EdgeDriver(options);

Enabling BiDi Protocol

import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.enableBiDi();
// Sets "webSocketUrl" capability to true
ChromeDriver driver = new ChromeDriver(options);

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_Browser_Options_Configuration