Implementation:SeleniumHQ Selenium Proxy
| Knowledge Sources | |
|---|---|
| Domains | WebDriver, Network_Configuration |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Configuration object for specifying HTTP, SSL, SOCKS, and PAC proxy settings in Selenium WebDriver sessions.
Description
The Proxy class provides a comprehensive API for configuring proxy settings used during WebDriver browser sessions. It supports multiple proxy strategies through the ProxyType enum: DIRECT (no proxy), MANUAL (explicit host:port settings for HTTP, SSL, and SOCKS protocols), PAC (proxy auto-configuration via URL), AUTODETECT (WPAD-based auto-detection), and SYSTEM (inherit OS-level proxy settings). The class enforces mutual exclusivity between proxy types at runtime -- once a proxy type is committed (e.g., by setting an HTTP proxy, which implicitly selects MANUAL), attempting to configure an incompatible type (e.g., PAC) throws an IllegalStateException. For SOCKS proxies, both version 4 and version 5 are supported, with optional username/password authentication available for SOCKS v5 and above. The class can serialize its state to a W3C-compliant JSON map via toJson() and can be reconstructed from a raw map via its Proxy(Map) constructor. A static extractFrom(Capabilities) method is provided to retrieve a Proxy instance from an existing Capabilities object.
Usage
Use this class when you need to route browser traffic through a proxy server during automated testing. Common scenarios include testing applications behind corporate proxies, capturing traffic with an intercepting proxy (e.g., BrowserMob, mitmproxy), bypassing certain hosts via the no-proxy list, or configuring SOCKS tunnels for network-restricted environments. Instantiate a Proxy object, configure the desired settings with the fluent setter API, and pass it to the browser options (e.g., ChromeOptions, FirefoxOptions) before creating the WebDriver session.
Code Reference
Source Location
- Repository: Selenium
- File: java/src/org/openqa/selenium/Proxy.java
- Lines: L37-515
Signature
public class Proxy {
public enum ProxyType {
DIRECT, MANUAL, PAC, RESERVED_1, AUTODETECT, SYSTEM, UNSPECIFIED
}
public Proxy();
public Proxy(Map<String, ?> raw);
public ProxyType getProxyType();
public Proxy setProxyType(ProxyType proxyType);
public boolean isAutodetect();
public Proxy setAutodetect(boolean autodetect);
public @Nullable String getHttpProxy();
public Proxy setHttpProxy(String httpProxy);
public @Nullable String getSslProxy();
public Proxy setSslProxy(String sslProxy);
public @Nullable String getSocksProxy();
public Proxy setSocksProxy(String socksProxy);
public @Nullable Integer getSocksVersion();
public Proxy setSocksVersion(Integer socksVersion);
public @Nullable String getSocksUsername();
public Proxy setSocksUsername(String username);
public @Nullable String getSocksPassword();
public Proxy setSocksPassword(String password);
public @Nullable String getNoProxy();
public Proxy setNoProxy(String noProxy);
public @Nullable String getProxyAutoconfigUrl();
public Proxy setProxyAutoconfigUrl(String proxyAutoconfigUrl);
@Deprecated public @Nullable String getFtpProxy();
@Deprecated public Proxy setFtpProxy(String ftpProxy);
public Map<String, Object> toJson();
public static @Nullable Proxy extractFrom(Capabilities capabilities);
}
Import
import org.openqa.selenium.Proxy;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| proxyType | ProxyType | No | The proxy strategy: DIRECT, MANUAL, PAC, AUTODETECT, SYSTEM, or UNSPECIFIED (default) |
| httpProxy | String | No | HTTP proxy host and port in "hostname:port" format |
| sslProxy | String | No | SSL/TLS tunnel proxy host and port in "hostname:port" format |
| socksProxy | String | No | SOCKS proxy host and port in "hostname:port" format |
| socksVersion | Integer | No | SOCKS protocol version: 4 or 5 |
| socksUsername | String | No | Username for SOCKS v5 authentication |
| socksPassword | String | No | Password for SOCKS v5 authentication |
| noProxy | String | No | Comma-separated list of hostnames or IP addresses to bypass the proxy |
| proxyAutoconfigUrl | String | No | URL to a PAC (proxy auto-configuration) file, e.g., "http://hostname:port/proxy.pac" |
| autodetect | boolean | No | Set to true to use WPAD-based proxy auto-detection |
| raw | Map<String, ?> | No | Raw capability map to construct a Proxy from (used by the Map constructor) |
Outputs
| Name | Type | Description |
|---|---|---|
| toJson() | Map<String, Object> | W3C-compliant proxy capability map containing only the non-null/non-default fields (proxyType, httpProxy, sslProxy, socksProxy, socksVersion, socksUsername, socksPassword, noProxy as List, proxyAutoconfigUrl, autodetect) |
| extractFrom() | Proxy or null | Extracts and returns a Proxy instance from a Capabilities object's "proxy" capability, or null if not present |
Usage Examples
Manual HTTP and SSL Proxy
import org.openqa.selenium.Proxy;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriver;
// 1. Create and configure proxy
Proxy proxy = new Proxy();
proxy.setHttpProxy("proxy.example.com:8080");
proxy.setSslProxy("proxy.example.com:8443");
proxy.setNoProxy("localhost,127.0.0.1,*.internal.net");
// 2. Attach proxy to browser options
ChromeOptions options = new ChromeOptions();
options.setProxy(proxy);
// 3. Launch browser with proxy settings
ChromeDriver driver = new ChromeDriver(options);
SOCKS v5 Proxy with Authentication
import org.openqa.selenium.Proxy;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.firefox.FirefoxDriver;
Proxy proxy = new Proxy();
proxy.setSocksProxy("socks-host.example.com:1080");
proxy.setSocksVersion(5);
proxy.setSocksUsername("myuser");
proxy.setSocksPassword("mypassword");
FirefoxOptions options = new FirefoxOptions();
options.setProxy(proxy);
FirefoxDriver driver = new FirefoxDriver(options);
PAC (Proxy Auto-Configuration)
import org.openqa.selenium.Proxy;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriver;
Proxy proxy = new Proxy();
proxy.setProxyAutoconfigUrl("http://internal.corp/proxy.pac");
// ProxyType is automatically set to PAC
ChromeOptions options = new ChromeOptions();
options.setProxy(proxy);
ChromeDriver driver = new ChromeDriver(options);
Direct Connection (No Proxy)
import org.openqa.selenium.Proxy;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriver;
Proxy proxy = new Proxy();
proxy.setProxyType(Proxy.ProxyType.DIRECT);
ChromeOptions options = new ChromeOptions();
options.setProxy(proxy);
ChromeDriver driver = new ChromeDriver(options);
Autodetect Proxy Settings
import org.openqa.selenium.Proxy;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.chrome.ChromeDriver;
Proxy proxy = new Proxy();
proxy.setAutodetect(true);
// ProxyType is automatically set to AUTODETECT
ChromeOptions options = new ChromeOptions();
options.setProxy(proxy);
ChromeDriver driver = new ChromeDriver(options);
Constructing Proxy from a Map
import org.openqa.selenium.Proxy;
import java.util.Map;
// Reconstruct a Proxy from a raw capability map (e.g., from JSON deserialization)
Map<String, String> rawProxy = Map.of(
"proxyType", "manual",
"httpProxy", "proxy.example.com:8080",
"sslProxy", "proxy.example.com:8443"
);
Proxy proxy = new Proxy(rawProxy);
// proxy.getProxyType() returns ProxyType.MANUAL
// proxy.getHttpProxy() returns "proxy.example.com:8080"