[java][BiDi] implement emulation.setTimezoneOverride

[Delta456]

User description

💥 What does this PR do?

Implements emulation.setTimezoneOverride for Selenium Java

🔧 Implementation Notes

Implemented as per W3C spec

💡 Additional Considerations

🔄 Types of changes

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

---

PR Type

Enhancement

---

Description

• Implements emulation.setTimezoneOverride BiDi command for Java

• Creates reusable AbstractOverrideParameters base class for override operations

• Refactors SetGeolocationOverrideParameters to extend new abstract class

• Adds comprehensive tests for timezone override in contexts and user contexts

---

Diagram Walkthrough

flowchart LR
  A["OverrideParameters<br/>Interface"] --> B["AbstractOverrideParameters<br/>Base Class"]
  B --> C["SetGeolocationOverrideParameters<br/>Refactored"]
  B --> D["SetTimezoneOverrideParameters<br/>New"]
  C --> E["Emulation<br/>setTimezoneOverride Method"]
  D --> E
  E --> F["SetTimezoneOverrideTest<br/>New Tests"]

Loading

File Walkthrough

	Relevant files
Enhancement	OverrideParameters.java New interface for override parameters                                        java/src/org/openqa/selenium/bidi/emulation/OverrideParameters.java New interface defining common contract for override parameters Declares contexts(), userContexts(), and toMap() methods Enables code reuse across different emulation override types +29/-0    AbstractOverrideParameters.java Abstract base class for override parameters                            java/src/org/openqa/selenium/bidi/emulation/AbstractOverrideParameters.java New abstract base class implementing OverrideParameters interface Provides shared implementation for contexts() and userContexts() methods Includes validation to prevent specifying both contexts and userContexts Implements toMap() with validation ensuring at least one is specified +59/-0    SetTimezoneOverrideParameters.java New timezone override parameters class                                      java/src/org/openqa/selenium/bidi/emulation/SetTimezoneOverrideParameters.java New class extending AbstractOverrideParameters for timezone override Accepts timezone string in constructor (e.g., "America/Los_Angeles" or "+05:30") Provides fluent API for specifying contexts or userContexts Implements W3C WebDriver BiDi specification +20/-0    Emulation.java Add setTimezoneOverride method to Emulation                            java/src/org/openqa/selenium/bidi/emulation/Emulation.java Added setTimezoneOverride() method to Emulation class Sends emulation.setTimezoneOverride BiDi command with parameters Validates parameters are non-null before sending Returns Map response from BiDi server +6/-0
Refactoring	SetGeolocationOverrideParameters.java Refactor to use abstract base class                                            java/src/org/openqa/selenium/bidi/emulation/SetGeolocationOverrideParameters.java Refactored to extend AbstractOverrideParameters instead of duplicating code Removed duplicate contexts(), userContexts(), and toMap() implementations Delegates to parent class methods while maintaining fluent API Simplified from 63 lines to 21 lines +7/-30
Bug fix	Command.java Remove immutable copy of command parameters                            java/src/org/openqa/selenium/bidi/Command.java Changed params assignment to remove Map.copyOf() wrapper Stores reference to original map instead of immutable copy Allows mutable parameter maps to be used in commands +1/-1
Tests	SetGeolocationOverrideTest.java Rename test class for clarity                                                        java/test/org/openqa/selenium/bidi/emulation/SetGeolocationOverrideTest.java Renamed test class from EmulationTest to SetGeolocationOverrideTest Improves test organization and clarity Aligns with new test file naming convention +1/-1      SetTimezoneOverrideTest.java New tests for timezone override functionality                        java/test/org/openqa/selenium/bidi/emulation/SetTimezoneOverrideTest.java New comprehensive test suite for timezone override functionality Tests timezone override in browsing contexts with named timezones Tests timezone override in user contexts Tests timezone override using UTC offset format (e.g., "+05:30") Verifies timezone is correctly applied and can be reset to original Uses JavaScript to validate timezone string and offset values +126/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

(Compliance updated until commit 9436fbc)

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
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
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing validation: SetTimezoneOverrideParameters accepts timezone without validating null/empty/format, risking invalid input to the BiDi command. Referred Code public SetTimezoneOverrideParameters(String timezone) { map.put("timezone", timezone); } Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No auditing: The new setTimezoneOverride operation performs a critical environment change without emitting any audit/log record, but logging patterns for this component are not visible in the diff. Referred Code public Map<String, Object> setTimezoneOverride(SetTimezoneOverrideParameters parameters) { Require.nonNull("SetTimezoneOverride parameters", parameters); return bidi.send(new Command<>("emulation.setTimezoneOverride", parameters.toMap(), Map.class)); } Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Partial validation: Context selection is validated, but there is no validation of the timezone value itself (null/empty/format), which may rely on external spec enforcement. Referred Code @Override public Map<String, Object> toMap() { // Validate that either contexts or userContexts is set if (!map.containsKey("contexts") && !map.containsKey("userContexts")) { throw new IllegalStateException("Must specify either contexts or userContexts"); } return new HashMap<>(map); } Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

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

---

Previous compliance checks

Compliance check up to commit 03173c2

Security Compliance
⚪	Mutable shared state Description: The change stores a direct reference to the provided params map instead of an immutable copy, allowing external mutation after command creation which could lead to parameter tampering or race conditions if the map is shared across threads. Command.java [47-53] Referred Code Map<String, Object> params, Function<JsonInput, X> mapper, boolean sendsResponse) { this.method = Require.nonNull("Method name", method); this.params = Require.nonNull("Command parameters", params); this.mapper = Require.nonNull("Mapper for result", mapper); this.sendsResponse = sendsResponse;
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
🟢	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
🔴	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing validation: The constructor accepts a timezone string without validating null/empty or format, risking invalid inputs propagating to the command. Referred Code public SetTimezoneOverrideParameters(String timezone) { map.put("timezone", timezone); }
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No audit logs: The new emulation timezone override command execution is not logged, making it unclear who set overrides and when. Referred Code public Map<String, Object> setTimezoneOverride(SetTimezoneOverrideParameters parameters) { Require.nonNull("SetTimezoneOverride parameters", parameters); return bidi.send(new Command<>("emulation.setTimezoneOverride", parameters.toMap(), Map.class)); }
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Inconsistent naming: Local variables like TzNew use inconsistent capitalization compared to others, slightly hurting readability. Referred Code String TzNew = getTimezoneString(driver, contextId); assert TzNew.equals(tzOrg) : "Timezone reset failed: expected " + tzOrg + ", got " + TzNew;
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Mutable params: Replacing the immutable Map.copyOf with a mutable map reference can allow external mutation of command parameters, potentially introducing security and reliability issues. Referred Code this.params = Require.nonNull("Command parameters", params); this.mapper = Require.nonNull("Mapper for result", mapper);

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	✅ Return a defensive copy of map Suggestion Impact: The commit updated the return statement to create and return a new HashMap from the internal map, implementing the defensive copy as suggested. code diff: - return map; + return new HashMap<>(map); Return a defensive copy of the internal map in the toMap() method to prevent external modification and maintain encapsulation. java/src/org/openqa/selenium/bidi/emulation/AbstractOverrideParameters.java [57] -return map; +return new HashMap<>(map); [Suggestion processed] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a significant encapsulation issue in the new AbstractOverrideParameters class where returning a direct reference to the internal map allows bypassing validation logic. Providing a defensive copy is crucial for maintaining the object's integrity.	Medium
Possible issue	✅ Create a defensive copy of parameters Suggestion Impact: The commit changed the assignment of params to wrap a new HashMap copy with Collections.unmodifiableMap, exactly implementing the defensive copy and immutability as suggested. code diff: + this.params = + Collections.unmodifiableMap( + new java.util.HashMap<>(Require.nonNull("Command parameters", params))); To ensure the Command object is immutable, create a defensive, unmodifiable copy of the params map that allows null values. java/src/org/openqa/selenium/bidi/Command.java [51] -this.params = Require.nonNull("Command parameters", params); +this.params = java.util.Collections.unmodifiableMap(new java.util.HashMap<>(Require.nonNull("Command parameters", params))); [Suggestion processed] Suggestion importance[1-10]: 7 __ Why: The PR removed Map.copyOf() which made the params map immutable but disallowed nulls. This suggestion correctly identifies that the new implementation is mutable from the outside and proposes a solution that restores immutability while still allowing null values, improving the robustness of the Command object.	Medium
Learned best practice	Validate timezone constructor input Validate timezone input (allow null for reset, otherwise non-empty) to prevent invalid values from reaching the BiDi command. java/src/org/openqa/selenium/bidi/emulation/SetTimezoneOverrideParameters.java [5-7] public SetTimezoneOverrideParameters(String timezone) { + if (timezone != null && timezone.isBlank()) { + throw new IllegalArgumentException("Timezone must be null (to reset) or a non-empty string"); + } map.put("timezone", timezone); } Apply / Chat Suggestion importance[1-10]: 5 __ Why: Relevant best practice - Guard external API and I/O operations with targeted validation to surface clear errors.	Low
Update

[navin772]

The 1st and 2nd comment by the AI bot makes sense, can you check it?

[navin772]

LGTM!