[🐛 Bug]: Incorrect type annotation for `locator` parameter in `expected_conditions.visibility_of_element_located`

[Next-Wave-Code]

Description

The type annotation for the locator parameter in selenium.webdriver.support.expected_conditions.visibility_of_element_located (and potentially other expected_conditions methods that accept a locator) is currently specified as tuple[str, str]. However, in practice, and as demonstrated in Selenium's own examples, the locator parameter expects a tuple[By, str], where By is an enum from selenium.webdriver.common.by.

This discrepancy leads to type checker errors (e.g., from Pylance or MyPy) when users correctly pass a locator in the format (By.ID, "some_id"). The type checker flags this as an incompatibility because By is not assignable to str.

Reproducible Code

1.  Install Selenium and a type checker (e.g., MyPy or Pylance).
2.  Use the following code snippet:


from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.remote.webdriver import WebDriver
from selenium.webdriver.remote.webelement import WebElement

# Assume 'driver' is an initialized WebDriver instance
# For demonstration purposes, we'll mock a WebDriver
class MockWebDriver:
    def find_element(self, by, value):
        print(f"Finding element by {by} with value {value}")
        return MockWebElement()

class MockWebElement:
    def is_displayed(self):
        return True

driver: WebDriver = MockWebDriver() # Replace with actual driver initialization in a real scenario

def my_wait_function(driver: WebDriver, locator: tuple[By, str]) -> WebElement:
    wait = WebDriverWait(driver, 10)
    # This line causes a type error due to Selenium's incorrect annotation
    return wait.until(EC.visibility_of_element_located(locator))

# Example usage that would trigger the type checker error
element = my_wait_function(driver, (By.ID, "some_element_id"))
print("Element found (type checker would flag the above line)")


**Expected Behavior:**
The type checker should not raise an error when `tuple[By, str]` is passed as the `locator` argument to `EC.visibility_of_element_located`, as this is the correct and intended usage.

**Actual Behavior:**
Type checkers (e.g., Pylance, MyPy) raise an error similar to:
`Argument of type "tuple[By, str]" cannot be assigned to parameter "locator" of type "tuple[str, str]" in function "visibility_of_element_located"`

**Selenium Version:** [Selenium version 4.35]
**Python Version:** [Python version 3.13+]

[selenium-ci]

@Next-Wave-Code, thank you for creating this issue. We will troubleshoot it as soon as we can.

Selenium Triage Team: remember to follow the Triage Guide

[Next-Wave-Code]

Update:

After further investigation into Selenium's type definitions (specifically selenium.webdriver.common.by.py), I've gained a clearer understanding of the intended type hinting for locators.

It appears that By.XPATH (and similar By attributes) are indeed string constants, and the ByType type alias is provided to represent these string values when type hinting locators.

Therefore, the correct type annotation for a locator tuple, such as (By.XPATH, "some_xpath_string"), should be tuple[ByType, str], not tuple[By, str]. When tuple[ByType, str] is used, Pylance correctly recognizes the type and the error is resolved.

My apologies for the initial confusion. It seems the issue was more related to a misunderstanding of Selenium's specific type hinting conventions rather than an incorrect annotation within Selenium itself.

Perhaps the documentation could be updated to more explicitly guide users on the use of ByType for locator type hints, as this could prevent similar confusion for others.

Thank you for your time and consideration.

[Next-Wave-Code]

"I'm sorry, I opened this issue without checking it in detail. After looking at it further, I realize my understanding of the issue was incorrect. Would it be possible to delete this issue to keep the tracker clean? Thank you for your time."