Skip to content

Add REMOTE_WEBDRIVER_TIMEOUT setting for Remote WebDriver HTTP requests - #4473

Merged
mdmintz merged 1 commit into
seleniumbase:masterfrom
TaylorMcGinnis:remote-webdriver-timeout
Aug 25, 2026
Merged

Add REMOTE_WEBDRIVER_TIMEOUT setting for Remote WebDriver HTTP requests#4473
mdmintz merged 1 commit into
seleniumbase:masterfrom
TaylorMcGinnis:remote-webdriver-timeout

Conversation

@TaylorMcGinnis

Copy link
Copy Markdown
Contributor

AI disclosure: I have been trying to pin down our node failures for a while now manually and with our selenium grid provider, but it is infrequent enough to be hard to pin down why they occur (and since they spin up AWS nodes on-demand, a lot of it is out of their control anyway). In an effort to avoid our tests running until our final-line-of-defense of the timeout in pytest-timeout plugin, I've leveraged Claude Code to diagnose this and suggest solutions. I have personally read through these changes and have a decent understanding, and believe this should be a safe setting to pass through to Selenium's RemoteWebDriver.


Add a REMOTE_WEBDRIVER_TIMEOUT setting (default None, which keeps the existing behavior). When set, get_remote_driver() builds a ClientConfig with that timeout and passes it to webdriver.Remote, so every HTTP request to the remote server gets a finite client-side deadline and a dead node surfaces as a ReadTimeoutError instead of an infinite hang. The setting matches other settings consumed via --settings-file.

Sizing guidance: set the value above PAGE_LOAD_TIMEOUT (a page navigation legitimately holds one request open that long) and above the time a new-session request may wait in the grid's session queue.

Selenium's ClientConfig defaults its HTTP timeout to socket.getdefaulttimeout(), which is None unless the application sets a process-wide socket default (which is rare), so a WebDriver command to a remote Selenium server blocks forever if a grid node dies with the TCP connection half-open.

Verified against a TCP server that accepts connections and never responds (simulating a dead node): with REMOTE_WEBDRIVER_TIMEOUT = 5, Driver(browser="chrome", server="127.0.0.1", port=5555) raises ReadTimeoutError ... (read timeout=5) after 5.0s. With the default (None), it blocks indefinitely — existing behavior is unchanged.

Also verified against a real Selenium Grid provider (Gridlastic): with selenium grid nodes warm (up, but not in use, ready for a new runner) and the setting intentionally at an extremely low setting of 2 seconds, a live session-creation request fails with ReadTimeoutError mid-queue as expected, and with the setting at 10 seconds, a 16-test run against warm grid nodes passes with zero false timeouts — every healthy request answered well inside even that aggressive ceiling. The default for real use should be generous (above PAGE_LOAD_TIMEOUT and the grid's new-session queue wait, which Gridlastic recommends a normal wait time being 3-5 minutes, with their maximum being 10 minutes); we would run REMOTE_WEBDRIVER_TIMEOUT at 660s. It is still basically a 'last line of defense' as far as the grid health is concerned, and we'll leave pytest-timeout as the true 'last line of defense'.

flake8 clean on the three touched files.

Also as a side note, remote_server_addr=address is set only because it is required for ClientConfig, even though Selenium's get_remote_connection sets it again, see https://github.com/SeleniumHQ/selenium/blob/5b3666d62507b79ae08b0bf0e18604c28bb8f404/py/selenium/webdriver/remote/webdriver.py#L113-L114

Selenium's ClientConfig defaults its HTTP timeout to socket.getdefaulttimeout(),
which is None, so a WebDriver command to a remote Selenium server blocks forever
if a grid node dies with the TCP connection half-open. The only way to bound this
today is to monkeypatch ClientConfig, because get_remote_driver() passes no
client_config to webdriver.Remote.

Add a REMOTE_WEBDRIVER_TIMEOUT setting (default None, which keeps the existing
behavior). When set, get_remote_driver() builds a ClientConfig with that timeout
and passes it to webdriver.Remote, so every HTTP request to the remote server
gets a finite client-side deadline and a dead node surfaces as a ReadTimeoutError
instead of a hang. The setting works with --settings-file like PAGE_LOAD_TIMEOUT.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mdmintz
mdmintz merged commit 2182f3c into seleniumbase:master Aug 25, 2026
6 checks passed
@TaylorMcGinnis
TaylorMcGinnis deleted the remote-webdriver-timeout branch August 26, 2026 02:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants