How to Use Proxies with Selenium

Selenium proxy configuration in Python

This example uses the standard Selenium proxy object and an IP-allowlisted endpoint. The same manual proxy is assigned to HTTP and HTTPS traffic.

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

proxy_host = os.environ["PROXY_HOST"]
proxy_port = os.environ["PROXY_PORT"]
endpoint = f"{proxy_host}:{proxy_port}"

proxy = Proxy()
proxy.proxy_type = ProxyType.MANUAL
proxy.http_proxy = endpoint
proxy.ssl_proxy = endpoint
proxy.no_proxy = "localhost,127.0.0.1"

options = webdriver.ChromeOptions()
options.proxy = proxy

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://api.ipify.org?format=json")
    result = json.loads(driver.find_element("tag name", "body").text)
    print("Proxy exit:", result["ip"])
finally:
    driver.quit()

The official driver session documentation includes proxy options in the browser configuration examples. Keep Selenium and the browser driver current enough to support the selected browser, and test a direct baseline before adding the proxy.

If you use an authenticated endpoint, do not hardcode credentials into endpoint. Standard HTTP proxy authentication support differs between browsers and drivers. Prefer an assigned IP allowlist when available, or a controlled local gateway that handles upstream authentication without exposing secrets to page content.

Chrome, Edge and Firefox considerations

Chromium-based browsers share many network behaviors, but Chrome, Edge and Firefox do not expose every authentication path identically. Use Selenium’s standard proxy capability first. Avoid a collection of browser-specific command-line flags unless the capability cannot express a documented requirement.

For Firefox, attach the same Proxy object to FirefoxOptions. For Edge, use EdgeOptions. Keep framework code small and push environment-specific addresses into configuration so the test logic does not change between local and CI runs.

Authenticated proxies in Selenium

A 407 response means the proxy needs valid authentication. Selenium can express SOCKS username and password in the Proxy object, but browser support and HTTP proxy challenge behavior still need real testing. For private HTTP proxies, the most portable options are usually provider-side IP allowlisting or a managed authentication component under your control.

Option 1: IP allowlisting

Allow the CI runner’s stable public IP in the proxy account, then configure only host and port in Selenium. This avoids placing a password in browser arguments or extension files. It is a strong fit for fixed runners, but not for laptops whose public IP changes frequently.

Option 2: managed browser extension

A Chrome extension can answer proxy authentication challenges, but it becomes a security-sensitive test dependency. Generate it at runtime from a template, restrict its permissions, never commit secrets, and delete the temporary directory after the driver quits. Revalidate the method when browser extension policies change.

Option 3: approved local gateway

A local forwarding service can receive unauthenticated traffic from the isolated test runner and authenticate to the upstream proxy. Bind it to localhost, restrict clients, protect logs and shut it down after the suite. Do not expose an open forwarding port.

The proxy authentication guide compares username/password and IP allowlisting in more detail.

Map WebDriver sessions to proxy sessions

A WebDriver session owns browser state. For account, checkout or multi-page QA, assign one stable proxy for the complete driver lifetime. Starting a new proxy halfway through a session can create location, cookie and risk inconsistencies that make a test fail for reasons unrelated to the application.

• Allocate the proxy before creating the driver.
• Verify the exit and expected country at the beginning.
• Keep one account, browser profile and proxy aligned.
• Do not share a mutable profile between parallel drivers.
• Quit the driver before releasing the proxy assignment.
• Quarantine endpoints that repeatedly fail the same health check.

Selenium Grid adds another layer: the browser node, not necessarily the test client, makes the destination connection. Confirm where the proxy is reachable from and where environment variables are applied. Record the node and proxy IDs in the test report without exposing credentials.

Troubleshoot Selenium proxy failures by layer

Do not solve a certificate error with a permanent insecure flag. Investigate the certificate name, trust chain, system clock and any authorized interception. Use the proxy error code guide and proxy tester before changing application assertions.

Use Selenium proxies for reproducible QA

Regional QA should define the country, browser, viewport, locale, time zone, account state and expected result. The proxy controls the network exit, not every location signal. Test redirects, localized content, consent, prices and forms with the same evidence template used by the website testing guide.

Capture screenshots after important transitions, but add the final URL, observed IP, browser version and expected outcome. A screenshot without context is difficult to reproduce. If the test collects public data, follow the responsible pacing and validation practices in the scraping proxy guide.

Minimal acceptance checklist

• The driver starts with expected capabilities.
• The IP-check page shows the assigned proxy exit.
• The target loads with the expected status and content.
• The session remains on one proxy through stateful steps.
• Failures include a screenshot, browser log and masked proxy ID.
• The driver always quits and temporary credential material is removed.

Selenium, Playwright or Puppeteer?

Use Selenium when broad WebDriver ecosystem support, existing Grid infrastructure or multi-language bindings are central. Choose Playwright when fast context isolation, integrated tracing and per-context proxy configuration fit the suite. Choose Puppeteer for focused Chrome or Firefox automation in a JavaScript codebase.

Do not migrate only because proxy configuration looks shorter in another tool. Compare browser coverage, team language, CI environment, diagnostics and the real test portfolio. A small proof using the same private proxy and target page reveals more than a generic feature table.