[py][bidi]: add set_timezone_override command in emulation

[navin772]

User description

🔗 Related Issues

💥 What does this PR do?

Adds support for the set_timezone_override command from the emulation module - https://w3c.github.io/webdriver-bidi/#command-emulation-setTimezoneOverride

🔧 Implementation Notes

Usage:

Using IANA Time Zones {AREA}/{LOCATION}:

1. Contexts

   driver.emulation.set_timezone_override(timezone="Asia/Tokyo", contexts=[context_id])

2. User contexts

   driver.emulation.set_timezone_override(timezone="America/New_York", user_contexts=[user_context])

Using Offset:

1. Setting timezone to India:

   driver.emulation.set_timezone_override(timezone="+05:30", contexts=[context_id])

Use None to clear/reset the timezone override:

driver.emulation.set_timezone_override(timezone=None, contexts=[context_id])

💡 Additional Considerations

When setting timezone using offset in Firefox, it returns UTC as timezone instead of the set timezone. So, I have marked the corresponding test as xfail.

🔄 Types of changes

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

---

PR Type

Enhancement

---

Description

• Adds set_timezone_override command to emulation module

• Supports IANA timezone names and offset strings

• Allows clearing timezone override by setting to None

• Includes comprehensive tests for contexts and user contexts

---

Diagram Walkthrough

flowchart LR
  A["Emulation Module"] -->|"set_timezone_override"| B["Timezone Override"]
  B -->|"IANA names or offsets"| C["Apply to Contexts"]
  B -->|"IANA names or offsets"| D["Apply to User Contexts"]
  B -->|"None value"| E["Clear Override"]

Loading

File Walkthrough

	Relevant files
Enhancement	emulation.py Implement set_timezone_override emulation command                py/selenium/webdriver/common/bidi/emulation.py Adds new set_timezone_override method to Emulation class Accepts timezone identifier (IANA name or offset string) or None Supports applying override to browsing contexts or user contexts Includes validation to ensure either contexts or user_contexts is provided Executes emulation.setTimezoneOverride command via BiDi protocol +35/-0
Tests	bidi_emulation_tests.py Add timezone override tests and helper functions                  py/test/selenium/webdriver/common/bidi_emulation_tests.py Adds helper functions to retrieve browser timezone string and offset Adds test for timezone override with browsing context Adds test for timezone override with user context Adds test for timezone override using offset strings with Firefox xfail marker Tests verify timezone changes and clearing with None value +79/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Misleading assertion message Description: The test asserts the timezone offset equals -330 minutes but the failure message mistakenly references -540, which can conceal real failures or mislead reviewers; while not exploitable, it degrades reliability of automated validation of the new feature. bidi_emulation_tests.py [285-293] Referred Code # set timezone to India (UTC+05:30) using offset driver.emulation.set_timezone_override(timezone="+05:30", contexts=[context_id]) timezone_offset = get_browser_timezone_offset(driver) timezone_string = get_browser_timezone_string(driver) # India is UTC+05:30, so the offset should be -330 minutes (negative because it's ahead of UTC) assert timezone_offset == -330, f"Expected timezone offset -540, got: {timezone_offset}" assert timezone_string == "+05:30", f"Expected timezone '+05:30', got: {timezone_string}"
Ticket Compliance
🟡	🎫 #1234 🔴 Investigate and fix regression where clicking a link with JavaScript in href no longer triggers in Selenium 2.48.x on Firefox 42 (alerts fire in 2.47.1).
🟡	🎫 #5678 🔴 Diagnose and resolve "Error: ConnectFailure (Connection refused)" occurring when instantiating additional ChromeDriver instances on Ubuntu with Selenium 3.9.0 and Chrome 65/ChromeDriver 2.35.
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
General	Verify timezone override is cleared Add an assertion to verify that the timezone override is successfully cleared and reverts to its initial state. py/test/selenium/webdriver/common/bidi_emulation_tests.py [268-273] +initial_timezone_string = get_browser_timezone_string(driver) + driver.emulation.set_timezone_override(timezone="America/New_York", user_contexts=[user_context]) timezone_string = get_browser_timezone_string(driver) assert timezone_string == "America/New_York", f"Expected timezone 'America/New_York', got: {timezone_string}" driver.emulation.set_timezone_override(timezone=None, user_contexts=[user_context]) +timezone_after_clear = get_browser_timezone_string(driver) +assert timezone_after_clear == initial_timezone_string + Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly points out that the test is incomplete because it doesn't verify that clearing the timezone override works. Adding this check makes the test more robust and thorough.	Low
Learned best practice	Add strict input validation Validate that when provided, contexts and user_contexts are non-empty lists of strings to avoid protocol errors. Also validate that timezone is a string when not None. py/selenium/webdriver/common/bidi/emulation.py [219-245] def set_timezone_override( self, timezone: Optional[str] = None, contexts: Optional[list[str]] = None, user_contexts: Optional[list[str]] = None, ) -> None: - ... + if contexts is not None and user_contexts is not None: + raise ValueError("Cannot specify both contexts and user_contexts") + if contexts is None and user_contexts is None: + raise ValueError("Must specify either contexts or user_contexts") + if timezone is not None and not isinstance(timezone, str): + raise TypeError("timezone must be a string or None") + if contexts is not None: + if not isinstance(contexts, list) or not contexts or not all(isinstance(c, str) and c for c in contexts): + raise ValueError("contexts must be a non-empty list of non-empty strings") + if user_contexts is not None: + if not isinstance(user_contexts, list) or not user_contexts or not all( + isinstance(u, str) and u for u in user_contexts + ): + raise ValueError("user_contexts must be a non-empty list of non-empty strings") params: dict[str, Any] = {"timezone": timezone} + if contexts is not None: + params["contexts"] = contexts + elif user_contexts is not None: + params["userContexts"] = user_contexts + self.conn.execute(command_builder("emulation.setTimezoneOverride", params)) [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Validate inputs and states early with precise checks to prevent logic errors.	Low
Possible issue	Fix incorrect assertion message value Fix an incorrect value in the assertion message for timezone_offset. The message expects -540 while the assertion correctly checks for -330. py/test/selenium/webdriver/common/bidi_emulation_tests.py [291-292] # India is UTC+05:30, so the offset should be -330 minutes (negative because it's ahead of UTC) -assert timezone_offset == -330, f"Expected timezone offset -540, got: {timezone_offset}" +assert timezone_offset == -330, f"Expected timezone offset -330, got: {timezone_offset}" Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies and fixes a copy-paste error in a test's assertion message, which improves the clarity and debuggability of the test failure.	Low
Update

[cgoldberg]

LGTM!