Configuring proxies in Selenium WebDriver without hidden dependencies
Selenium supplies proxy settings through browser options. Values must be reachable from the browser execution node, not only from the test launcher.
Key points in one minute
- Verify connectivity from the browser environment.
- Do not mix system proxy settings and capabilities without documentation.
- Network reachability must be verified from the browser node itself.
- Diagnostics should separate authentication, transport, TLS, and application response.
Explicit configuration
Set proxy type, host, and port in the browser options. Keep configuration with the environment definition, excluding secrets.
Describe configuration with typed protocol, host, port, and bypass fields, and retrieve secrets from protected storage only at runtime. Validate port ranges and allowed schemes before creating the driver. Log the environment name and a safe credential identifier, but never a password-bearing URL or Proxy-Authorization header.
Local execution and Grid
In Grid, the browser may run on another node. Localhost then refers to the browser node, not the engineer's machine.
For Grid, create a reachability table across runner, hub, browser node, and proxy host. An address reachable from an engineer's laptop may be unreachable from a node container. Test DNS, TCP connectivity, and egress rules separately. Use a neutral service name instead of localhost and bind it to the specific environment configuration.
Diagnostic test
Before the full suite, test one authorized page, expected status, outbound address, and a second independent endpoint. This isolates infrastructure from test logic.
The smoke check should distinguish 407, TCP refusal, TLS failure, HTTP 4xx or 5xx, and an incorrect outbound route. Make two short requests to authorized independent endpoints and record connect time and overall outcome. If both fail identically, stop the suite before heavy scenarios; if only one fails, investigate that destination separately.
Cleanup
Always quit the driver after exceptions to prevent connection and process buildup. Revoke temporary-environment credentials afterward.
Wrap the driver lifecycle in try/finally and apply a bounded shutdown timeout. After each run, monitor browser-process count, open connections, and consumed Grid sessions. Growth across builds indicates a resource leak. Revoke temporary credentials after the last session closes rather than on a fixed timer during the test.
Practical checklist
- 1Check proxy-host reachability from the browser node.
- 2Run a short smoke test.
- 3Guarantee driver.quit during cleanup.
- 4Check two independent endpoints before the suite.
- 5Monitor processes and Grid sessions after cleanup.
Sources and documentation
This material is based on primary, official, and technical sources. The article is an original summary written for this knowledge base.