How to Configure Proxy Servers in Selenium?

What is Selenium Proxy

A proxy in Selenium is a server that sits between the test browser and the target application. It routes requests and responses, allowing testers to control and inspect network traffic during automated runs. Using a proxy helps when tests need to simulate users from different regions, apply security rules, or capture HTTP data for debugging.

In Selenium, proxies are configured at the WebDriver level. Once set, every request made by the browser goes through the proxy before reaching the destination server. This gives testers a central point to manage restrictions, authentication, and logging.

Types of Selenium Proxy

Selenium does not restrict you to a single kind of proxy. Depending on the network setup and the type of application under test, you may need different proxy configurations. Each type changes how traffic flows between the WebDriver-controlled browser and the destination server. Here are the main types and their specific testing use cases:

1. HTTP Proxy

This proxy only supports unencrypted HTTP requests. Since it does not perform SSL/TLS handshakes, it is faster but less secure. In Selenium, it is often used in internal or staging environments where encryption is not required but you still need to capture or reroute traffic. 

For example, QA teams may run regression suites through an HTTP proxy to log all requests for debugging without worrying about certificate validation.

2. HTTPS Proxy

This proxy handles encrypted HTTPS traffic. To make Selenium work with it, the WebDriver or the underlying browser must be configured to trust the proxy’s SSL certificate. Without this, you will see certificate validation errors and failed requests. 

HTTPS proxies are required in realistic test setups that mirror production security conditions. They allow testers to analyze secure traffic while keeping encryption intact.

3. SOCKS Proxy

Unlike HTTP or HTTPS proxies, a SOCKS proxy works at the transport layer and can forward multiple types of traffic, including HTTP, HTTPS, FTP, and even UDP. 

In Selenium, this becomes important when the application uses WebSockets or API calls in parallel with standard web requests. SOCKS proxies are also widely used for geo-testing. By tunneling all browser traffic through a proxy server located in another country, teams can validate how content is served to users in different regions.

4. Transparent Proxy

A transparent proxy does not require browser-level configuration and forwards traffic without altering headers or enforcing authentication. While it is less common in Selenium test execution, it is valuable in compliance-driven environments. 

For example, financial institutions may run tests behind a transparent proxy to keep an audit log of all browser activity without interfering with the test flow. Since the browser is unaware of the proxy, there is no need for additional setup in Selenium scripts.

Selenium Proxy Authentication: Username-Password vs IP Whitelist

When you configure Selenium with a proxy, authentication is often required to allow the browser traffic through. There are two common approaches: username-password credentials or IP whitelisting. Both methods achieve the same goal but differ in how they are applied and maintained. 

Here are the key differences between username-password vs IP whitelist in Selenium Proxy authentication. 

How to Set Up Proxy Servers in Selenium WebDriver

Selenium WebDriver lets you configure proxies directly in the browser session before any test runs. The approach is consistent across browsers, but the exact steps vary depending on the driver and language bindings. In practice, the setup always involves three actions:

• Defining the proxy type and server address.
• Passing the proxy configuration into the browser capabilities.
• Launching the WebDriver session with those capabilities.

Once configured, every request from Selenium will be routed through the proxy server. This makes it possible to monitor, restrict, or redirect traffic as needed.

The next two sections explain how to implement proxies in Selenium, first without authentication and then with authentication.

Implementing HTTP Proxy Without Authentication

When the proxy does not require credentials, configuration is straightforward. Set the proxy host and port, attach the proxy to the browser capabilities or options, then start the browser. Below are concrete steps, practical tips, and working examples in Python and Java.

Prelude: do these three things in order. First set the proxy address and type. Second, attach the proxy to the browser capabilities or options. Third, launch the WebDriver session and validate the traffic is routed through the proxy.

Here are the practical steps you will follow:

1. Declare the proxy host and port.
2. Configure the proxy fields required for your protocol. For plain HTTP set http proxy. For secure endpoints also set ssl proxy. For SOCKS set socks proxy and socks version.
3. Add the proxy configuration to browser capabilities or options.
4. Launch the browser and validate the proxy by visiting an IP lookup endpoint or an internal test endpoint.

Below are ready-to-run examples.

Python (Selenium 4) — Chrome and Firefox

# Python example using Proxy.add_to_capabilities

from selenium import webdriver

from selenium.webdriver.common.proxy import Proxy, ProxyType

# 1. proxy address

proxy_host = "10.20.30.40:3128"

# 2. build proxy object

proxy = Proxy()

proxy.proxy_type = ProxyType.MANUAL

proxy.http_proxy = proxy_host

proxy.ssl_proxy = proxy_host

# if using SOCKS:

# proxy.socks_proxy = "10.20.30.40:1080"

# proxy.socks_version = 5

# 3. add to capabilities

capabilities = webdriver.DesiredCapabilities.CHROME.copy()

proxy.add_to_capabilities(capabilities)

# 4. launch Chrome with proxy

driver = webdriver.Chrome(desired_capabilities=capabilities)

driver.get("https://ifconfig.me")  # or another IP-check endpoint

print(driver.title)

driver.quit()

# For Firefox, reuse the same capabilities approach

capabilities_ff = webdriver.DesiredCapabilities.FIREFOX.copy()

proxy.add_to_capabilities(capabilities_ff)

driver_ff = webdriver.Firefox(desired_capabilities=capabilities_ff)

driver_ff.get("https://ifconfig.me")

driver_ff.quit()

Notes for Python:

• Set both http_proxy and ssl_proxy if your tests hit HTTPS endpoints.
• For SOCKS use socks_proxy and socks_version.
• If you use browser-specific Options objects, you can also set capabilities via options.set_capability(...) before creating the driver.

Java — Chrome and Firefox

// Java example using org.openqa.selenium.Proxy and ChromeOptions

import org.openqa.selenium.Proxy;

import org.openqa.selenium.WebDriver;

import org.openqa.selenium.chrome.ChromeDriver;

import org.openqa.selenium.chrome.ChromeOptions;

import org.openqa.selenium.remote.CapabilityType;

public class ProxyExample {

  public static void main(String[] args) {

    String proxyAddr = "10.20.30.40:3128";

    Proxy proxy = new Proxy();

    proxy.setProxyType(Proxy.ProxyType.MANUAL);

    proxy.setHttpProxy(proxyAddr);

    proxy.setSslProxy(proxyAddr);

    // for SOCKS: proxy.setSocksProxy("10.20.30.40:1080"); proxy.setSocksVersion(5);

    ChromeOptions options = new ChromeOptions();

    options.setCapability(CapabilityType.PROXY, proxy);

    WebDriver driver = new ChromeDriver(options);

    driver.get("https://ifconfig.me");

    System.out.println(driver.getTitle());

    driver.quit();

  }

}

Notes for Java:

• Use setHttpProxy and setSslProxy together for sites that use HTTPS.
• For Firefox use FirefoxOptions and set the same CapabilityType.PROXY.

Implementing Authenticated Proxy in Selenium Scripts

Some proxies do not allow traffic without credentials. In such cases, Selenium needs to send a username and password before the browser session can proceed. There are two main ways to achieve this: by embedding the credentials directly in the proxy URL or by handling authentication prompts programmatically. Both approaches come with trade-offs in security and maintainability.

Here are the common methods you can use:

1. Embed credentials in the proxy URL‍

This is the simplest method. The proxy address is written in the form username:password@host:port. While easy to configure, this method can expose credentials in logs or stack traces.Python Example:

Python Example:

from selenium import webdriver

from selenium.webdriver.common.proxy import Proxy, ProxyType

proxy = Proxy()

proxy.proxy_type = ProxyType.MANUAL

proxy.http_proxy = "user:pass@10.20.30.40:3128"

proxy.ssl_proxy = "user:pass@10.20.30.40:3128"

capabilities = webdriver.DesiredCapabilities.CHROME.copy()

proxy.add_to_capabilities(capabilities)

driver = webdriver.Chrome(desired_capabilities=capabilities)

driver.get("https://ifconfig.me")

driver.quit()

Java Example:

import org.openqa.selenium.Proxy;

import org.openqa.selenium.WebDriver;

import org.openqa.selenium.chrome.ChromeDriver;

import org.openqa.selenium.chrome.ChromeOptions;

import org.openqa.selenium.remote.CapabilityType;

public class AuthProxyExample {

  public static void main(String[] args) {

    String proxyAuth = "user:pass@10.20.30.40:3128";

    Proxy proxy = new Proxy();

    proxy.setHttpProxy(proxyAuth);

    proxy.setSslProxy(proxyAuth);

    ChromeOptions options = new ChromeOptions();

    options.setCapability(CapabilityType.PROXY, proxy);

    WebDriver driver = new ChromeDriver(options);

    driver.get("https://ifconfig.me");

    driver.quit();

  }

}

2. Handle browser authentication pop-ups‍

Some proxies trigger a login prompt instead of allowing credentials in the URL. Selenium cannot directly interact with these dialogs, so the workaround is to use browser profiles or extensions that inject credentials automatically.

• Chrome: You can create a Chrome extension with a background script that sets the Proxy-Authorization header.
• Firefox: You can preload a Firefox profile with proxy settings and credentials.

3. IP-based fallback‍

If authentication prompts cannot be bypassed reliably in automation, some teams combine username-password proxies with IP whitelisting for CI pipelines. This avoids the prompt entirely when tests are executed from trusted infrastructure.

Common Selenium Proxy Challenges

Working with proxies in Selenium is useful but often introduces technical hurdles. Below are the most frequent challenges you will encounter:

• SSL certificate errors: When a proxy intercepts HTTPS traffic, it often resigns the connection with its own certificate. Browsers under Selenium control reject these certificates unless explicitly trusted, causing failed secure connections and blocking test execution.
• Authentication prompts: Some proxies return a native browser login dialog instead of accepting credentials in the URL. Selenium cannot handle these dialogs directly, so tests either hang or fail. Workarounds include using browser profiles, extensions, or alternative authentication methods.
• IP whitelist mismatches: With IP-based authentication, dynamic IPs from cloud test grids, CI/CD pipelines, or containerized runners often change. This makes it impossible to maintain a stable whitelist, leading to frequent “access denied” errors during tests.
• Header rewriting: Certain proxies remove or replace request headers such as User-Agent, Authorization, or X-Forwarded-For. This disrupts scenarios where applications rely on those headers for authentication, analytics, or personalization, and causes test assertions to fail.
• WebSocket and HTTP/2 failures: Proxies limited to HTTP/1.1 often fail to upgrade connections for WebSockets or to handle HTTP/2 frames. Real-time features such as chat, live notifications, or streaming break, leaving automated tests incomplete.
• Rotating proxy IPs: Some proxy providers use IP rotation for anonymity. This can interrupt active sessions because the application sees multiple IPs during a single login flow, forcing re-authentication or blocking the session entirely.
• Latency issues: Proxies introduce additional hops and inspection steps that slow down response times. For test automation, this can cause scripts with strict wait conditions to fail or make regression suites take significantly longer to run.
• Log correlation problems: Proxy logs and Selenium logs live in separate systems. Without correlation identifiers, it is difficult to trace a failed browser action back to a specific network request, extending debugging cycles.
• Profile or extension conflicts: Handling proxies with custom browser profiles or authentication extensions can create side effects. These include altered browser behavior, unexpected DOM changes, or compatibility issues with the application under test.
• Caching side effects: Proxies that cache responses or browsers with service workers can serve stale data. Tests that expect a fresh response from the server instead see cached results, masking actual application behavior and leading to false positives.

Conclusion

Configuring proxies in Selenium gives testers the ability to control how browser traffic is routed, inspected, and authenticated. From choosing the right proxy type to handling authentication methods and troubleshooting issues, every detail matters for keeping tests stable and reflective of real user conditions.

While local proxy setups are useful for controlled environments, running Selenium tests on BrowserStack provides a more scalable option. BrowserStack offers built-in support for proxy configurations, cloud infrastructure with fixed IP ranges, and real device coverage. This allows teams to run reliable cross-browser tests without maintaining proxy servers or debugging complex network issues on local grids.