[java] Add web socket timeout for java binding

[iampopovich]

User description

🔗 Related Issues

fixes #16270

💥 What does this PR do?

This pull request adds support for configuring WebSocket timeout and interval settings for BiDi (Bidirectional) connections in both Chromium and Firefox drivers. It introduces new options in ChromiumOptions and FirefoxOptions to allow users to customize these settings, and propagates these configurations through the driver and HTTP client layers. The changes also ensure these settings are merged and exported as capabilities, making them available throughout the driver lifecycle.

🔧 Implementation Notes

WebSocket Timeout and Interval Configuration Support

• Added webSocketTimeout and webSocketInterval fields, along with corresponding setter and getter methods, to both ChromiumOptions and FirefoxOptions, allowing users to customize WebSocket communication timing. These are also included in the set of extra capability names and exported as capabilities (se:webSocketTimeout and se:webSocketInterval).

• Updated the constructors of ChromiumDriver and FirefoxDriver to extract the new WebSocket timeout and interval capabilities and pass them to the BiDi connection logic, ensuring the driver uses the configured values.

• Modified the createBiDi methods in both drivers to accept and use the WebSocket timeout and interval values when creating the WebSocket client configuration.

HTTP Client Configuration Enhancements

• Extended ClientConfig to support webSocketTimeout and webSocketInterval fields, with associated builder methods and propagation through all configuration methods. Updated default values and ensured these settings are applied when constructing HTTP clients for WebSocket communication.

Other Minor Updates

• Added necessary imports for Duration in relevant files. [

💡 Additional Considerations

🔄 Types of changes

• New feature (non-breaking change which adds functionality and tests!)

---

PR Type

Enhancement

---

Description

• Add WebSocket timeout and interval configuration support for BiDi connections in Java bindings

• Extend ChromiumOptions and FirefoxOptions with WebSocket timing setters/getters and capability export

• Propagate WebSocket configuration through driver constructors and HTTP client layers

• Update ClientConfig and JdkHttpClient to support and apply WebSocket timeout/interval settings

---

Diagram Walkthrough

flowchart LR
  Options["ChromiumOptions/FirefoxOptions"] -- "WebSocket config" --> Driver["ChromiumDriver/FirefoxDriver"]
  Driver -- "Extract capabilities" --> BiDi["BiDi Connection"]
  BiDi -- "Apply settings" --> ClientConfig["ClientConfig"]
  ClientConfig -- "Configure client" --> JdkHttpClient["JdkHttpClient"]

Loading

File Walkthrough

Relevant files

Enhancement

ChromiumDriver.java Extract and apply WebSocket configuration in ChromiumDriver java/src/org/openqa/selenium/chromium/ChromiumDriver.java Extract WebSocket timeout and interval from capabilities with default values Pass WebSocket configuration to createBiDi method Update BiDi creation to use configured timeout and interval in ClientConfig +21/-3    ChromiumOptions.java Add WebSocket configuration fields and capabilities to ChromiumOptions java/src/org/openqa/selenium/chromium/ChromiumOptions.java Add webSocketTimeout and webSocketInterval fields with default values Implement setter/getter methods for WebSocket timing configuration Export WebSocket settings as se:webSocketTimeout and se:webSocketInterval capabilities Merge WebSocket configuration in mergeInPlace method +65/-1    FirefoxDriver.java Extract and apply WebSocket configuration in FirefoxDriver java/src/org/openqa/selenium/firefox/FirefoxDriver.java Extract WebSocket timeout and interval from capabilities with defaults Pass WebSocket configuration to createBiDi method Configure ClientConfig with WebSocket timeout and interval for BiDi connection +21/-3    FirefoxOptions.java Add WebSocket configuration fields and capabilities to FirefoxOptions java/src/org/openqa/selenium/firefox/FirefoxOptions.java Add webSocketTimeout and webSocketInterval fields with default values Implement setter/getter methods for WebSocket timing configuration Export WebSocket settings as capabilities in getExtraCapability Add WebSocket capability names to getExtraCapabilityNames +51/-0    ClientConfig.java Extend ClientConfig with WebSocket timeout and interval support java/src/org/openqa/selenium/remote/http/ClientConfig.java Add webSocketTimeout and webSocketInterval fields to configuration Implement builder methods for WebSocket timeout and interval Set default values from system properties or hardcoded defaults Propagate WebSocket settings through all configuration methods +68/-0    JdkHttpClient.java Apply WebSocket timeout configuration in JdkHttpClient      java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java Add webSocketTimeout and webSocketInterval fields from ClientConfig Apply webSocketTimeout instead of readTimeout for WebSocket operations Use configured timeout for WebSocket connection establishment and message sending +6/-2

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🔴	Timeout unit mismatch Description: Inconsistent unit handling for capability 'se:webSocketTimeout': ChromiumDriver treats it as seconds while FirefoxDriver treats it as milliseconds, which can cause unexpectedly long or short timeouts and impact stability. FirefoxDriver.java [164-167] Referred Code Object timeoutCapability = capabilities.getCapability("se:webSocketTimeout"); if (timeoutCapability instanceof Number) { webSocketTimeout = Duration.ofMillis(((Number) timeoutCapability).longValue()); }
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	No custom compliance provided Follow the guide to enable custom compliance check.
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Unify timeout and interval units Standardize the units used for WebSocket timeout and interval values across all classes. Currently, ChromiumOptions exports timeout in seconds while FirefoxOptions uses milliseconds, creating an inconsistency that should be resolved by using a single unit like milliseconds everywhere. Examples: java/src/org/openqa/selenium/chromium/ChromiumOptions.java [280] return webSocketTimeout.toSeconds(); java/src/org/openqa/selenium/firefox/FirefoxOptions.java [330] return webSocketTimeout.toMillis(); Solution Walkthrough: Before: // In ChromiumOptions.java protected Object getExtraCapability(String capabilityName) { if ("se:webSocketTimeout".equals(capabilityName)) { return webSocketTimeout.toSeconds(); // Exports as seconds } // ... } // In FirefoxOptions.java protected Object getExtraCapability(String capabilityName) { if ("se:webSocketTimeout".equals(capabilityName)) { return webSocketTimeout.toMillis(); // Exports as milliseconds } // ... } // In ChromiumDriver.java Object timeoutCapability = ...getCapability("se:webSocketTimeout"); webSocketTimeout = Duration.ofSeconds(((Number) timeoutCapability).longValue()); // Interprets as seconds // In FirefoxDriver.java Object timeoutCapability = ...getCapability("se:webSocketTimeout"); webSocketTimeout = Duration.ofMillis(((Number) timeoutCapability).longValue()); // Interprets as milliseconds After: // In ChromiumOptions.java protected Object getExtraCapability(String capabilityName) { if ("se:webSocketTimeout".equals(capabilityName)) { return webSocketTimeout.toMillis(); // Exports as milliseconds } // ... } // In FirefoxOptions.java protected Object getExtraCapability(String capabilityName) { if ("se:webSocketTimeout".equals(capabilityName)) { return webSocketTimeout.toMillis(); // Exports as milliseconds } // ... } // In ChromiumDriver.java Object timeoutCapability = ...getCapability("se:webSocketTimeout"); webSocketTimeout = Duration.ofMillis(((Number) timeoutCapability).longValue()); // Interprets as milliseconds // In FirefoxDriver.java Object timeoutCapability = ...getCapability("se:webSocketTimeout"); webSocketTimeout = Duration.ofMillis(((Number) timeoutCapability).longValue()); // Interprets as milliseconds Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a critical design flaw where ChromiumOptions and FirefoxOptions export the same capability (se:webSocketTimeout) with different units (seconds vs. milliseconds), leading to inconsistent behavior and potential bugs.	High
Possible issue	Ensure consistent timeout unit across drivers In FirefoxDriver, change the unit for the se:webSocketTimeout capability from milliseconds to seconds to ensure consistency with ChromiumDriver. java/src/org/openqa/selenium/firefox/FirefoxDriver.java [164-167] Object timeoutCapability = capabilities.getCapability("se:webSocketTimeout"); if (timeoutCapability instanceof Number) { - webSocketTimeout = Duration.ofMillis(((Number) timeoutCapability).longValue()); + webSocketTimeout = Duration.ofSeconds(((Number) timeoutCapability).longValue()); } Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies an inconsistency in how the se:webSocketTimeout capability is handled between FirefoxDriver (milliseconds) and ChromiumDriver (seconds), and proposes a change to align them, improving framework consistency.	Medium
	Export timeout capability in seconds In FirefoxOptions, change the export unit for the se:webSocketTimeout capability from milliseconds to seconds to align with ChromiumOptions. java/src/org/openqa/selenium/firefox/FirefoxOptions.java [329-331] if ("se:webSocketTimeout".equals(capabilityName)) { - return webSocketTimeout.toMillis(); + return webSocketTimeout.toSeconds(); } Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that FirefoxOptions exports se:webSocketTimeout in milliseconds, which is inconsistent with ChromiumOptions (seconds). Aligning this improves consistency across browser options.	Medium
General	Correct inaccurate Javadoc for interval unit Correct the Javadoc for setWebSocketInterval and getWebSocketInterval to state that the interval unit is milliseconds, not seconds. java/src/org/openqa/selenium/chromium/ChromiumOptions.java [245-263] /** - * Sets the WebSocket response wait interval (in seconds) used for communicating with the browser. + * Sets the WebSocket response wait interval (in milliseconds) used for communicating with the browser. * * @param interval WebSocket response wait interval * @return A self reference. */ public T setWebSocketInterval(Duration interval) { this.webSocketInterval = Require.nonNull("WebSocket interval", interval); return (T) this; } /** - * Gets the WebSocket response wait interval (in seconds) used for communicating with the browser. + * Gets the WebSocket response wait interval (in milliseconds) used for communicating with the browser. * * @return WebSocket response wait interval */ public Duration getWebSocketInterval() { return webSocketInterval; } Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the Javadoc for setWebSocketInterval and getWebSocketInterval incorrectly states the unit is seconds when it is milliseconds, and fixing it improves documentation accuracy.	Low
Update

[iampopovich]

based on the test in python implementation i added properties with duration seconds and milliseconds
https://github.com/SeleniumHQ/selenium/pull/16248/files#diff-d7e08eadd4f84a4b0574e9d4a0927715c6d80f85b263485272346d8dc99a6821

def test_default_websocket_settings():
    config = ClientConfig(remote_server_addr="http://localhost:4444")
    assert config.websocket_timeout == 30.0
    assert config.websocket_interval == 0.1

should it be both of milliseconds ?

[titusfortner]

We need to keep these parameters contained to the client config class. The BiDi spec doesn't manage any timeouts, so we don't need to have options that get sent to the browser, and we don't want the driver juggling this directly.

Check out #13190 where we create a BiDi command executor to manage all of this. I'm not sure how close to ready that PR is I haven't looked at it in a while, but we actually want to pull this code out of the individual drivers.

[cgoldberg]

should it be both of milliseconds ?

In Python, both values are in seconds. (defaults are 30.0 and 0.1)

We need to keep these parameters contained to the client config class

In Python, we have websocket_timeout and websocket_interval attributes on the ClientConfig class. The defaults can be overriden in the contructor. This follows the same design as we already use for setting HTTP timeouts.

Here is an example of instantiating a Remote webdriver with a ClientConfig using custom websocket timeouts:

selenium/py/test/selenium/webdriver/remote/remote_connection_tests.py

Line 67 in e71fa0a

client_config = ClientConfig(

[diemol]

We need to get the ClientConfig all they way down to the drivers. I would like to avoid this approach.