What happened?

Bug description

The frame_to_be_available_and_switch_to_it function in the expected_conditions module of the Selenium Python library has an incorrect or outdated type annotation for its locator parameter. The current type annotation is Union[Tuple[str, str], str] which does not include WebElement objects as a valid argument type.

However, the implementation of the frame_to_be_available_and_switch_to_it function correctly handles WebElement objects as the locator argument. When a WebElement object is passed as the locator, the function successfully switches to the corresponding iframe.

This issue can be reproduced by running the attached snippet which demonstrates the frame_to_be_available_and_switch_to_it function working correctly with a WebElement object representing an iframe. When running the script, the output will include the line:

Type of iframe_element: <class 'selenium.webdriver.remote.webelement.WebElement'>

This output confirms that the frame_to_be_available_and_switch_to_it function indeed accepts a WebElement object as the locator argument, despite the incorrect type annotation.

Proposed solution

To address this issue, the type annotation for the locator parameter in the frame_to_be_available_and_switch_to_it function should be updated to accurately reflect the accepted argument types. The correct type annotation should be:

locator: Union[Tuple[str, str], str, WebElement]

This updated type annotation includes WebElement as a valid type for the locator argument, aligning with the function's implementation and behaviour.

Additionally, the documentation and docstring for the frame_to_be_available_and_switch_to_it function should be updated to mention that the locator parameter can accept a WebElement object representing the iframe element, in addition to tuples and strings.

By making these changes, the type annotation and documentation will accurately reflect the function's capabilities, improving code maintainability, clarity and type safety for developers using the Selenium Python library.

How can we reproduce the issue?

from selenium import webdriver
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.chrome.options import Options as ChromeOptions

options = ChromeOptions()
options.add_argument("--incognito")
options.binary_location = "PATH_TO_CHROMIUM"

driver = webdriver.Chrome(options=options)

driver.get("https://seleniumbase.io/w3schools/iframes")

iframe_container = driver.find_element(By.ID, "iframecontainer")
iframe_wrapper = iframe_container.find_element(By.ID, "iframe")
iframe_element = iframe_wrapper.find_element(By.ID, "iframeResult")

print(f"Type of iframe_element: {type(iframe_element)}")

try:
    WebDriverWait(driver, 10).until(EC.frame_to_be_available_and_switch_to_it(iframe_element))

    iframe_body = driver.find_element(By.TAG_NAME, "body")
except Exception as e:
    print(f"Error: {e}")
finally:
    driver.switch_to.default_content()

    driver.quit()

Relevant log output

pytest test_iframe.py
Type of iframe_element: <class 'selenium.webdriver.remote.webelement.WebElement'>

Operating System

macOS 15.3

Selenium version

Python 3.13.0

What are the browser(s) and version(s) where you see this issue?

Version 118.0.5993.0 (Developer Build) (arm64)

What are the browser driver(s) and version(s) where you see this issue?

118.0.5993.0

Are you using Selenium Grid?

No response