diff --git a/py/selenium/webdriver/support/expected_conditions.py b/py/selenium/webdriver/support/expected_conditions.py index f418a214e3b49..9f6936eec27e5 100644 --- a/py/selenium/webdriver/support/expected_conditions.py +++ b/py/selenium/webdriver/support/expected_conditions.py @@ -48,8 +48,14 @@ def title_is(title: str) -> Callable[[WebDriver], bool]: """An expectation for checking the title of a page. - title is the expected title, which must be an exact match returns - True if the title matches, false otherwise. + Parameters: + ---------- + title : str + The expected title, which must be an exact match. + + Returns: + ------- + boolean : True if the title matches, False otherwise. """ def _predicate(driver: WebDriver): @@ -62,8 +68,14 @@ def title_contains(title: str) -> Callable[[WebDriver], bool]: """An expectation for checking that the title contains a case-sensitive substring. - title is the fragment of title expected returns True when the title - matches, False otherwise + Parameters: + ---------- + title : str + The fragment of title expected. + + Returns: + ------- + boolean : True when the title matches, False otherwise. """ def _predicate(driver: WebDriver): @@ -76,8 +88,22 @@ def presence_of_element_located(locator: Tuple[str, str]) -> Callable[[WebDriver """An expectation for checking that an element is present on the DOM of a page. This does not necessarily mean that the element is visible. - locator - used to find the element - returns the WebElement once it is located + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + + Returns: + ------- + WebElement : The WebElement once it is located. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.presence_of_element_located((By.NAME, "q"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -90,8 +116,14 @@ def url_contains(url: str) -> Callable[[WebDriver], bool]: """An expectation for checking that the current url contains a case- sensitive substring. - url is the fragment of url expected, returns True when the url - matches, False otherwise + Parameters: + ---------- + url : str + The fragment of url expected. + + Returns: + ------- + boolean : True when the url matches, False otherwise. """ def _predicate(driver: WebDriver): @@ -103,9 +135,18 @@ def _predicate(driver: WebDriver): def url_matches(pattern: str) -> Callable[[WebDriver], bool]: """An expectation for checking the current url. - pattern is the expected pattern. This finds the first occurrence of - pattern in the current url and as such does not require an exact - full match. + Parameters: + ---------- + pattern : str + The pattern to match with the current url. + + Returns: + ------- + boolean : True when the pattern matches, False otherwise. + + Notes: + ------ + More powerful than url_contains, as it allows for regular expressions. """ def _predicate(driver: WebDriver): @@ -117,8 +158,14 @@ def _predicate(driver: WebDriver): def url_to_be(url: str) -> Callable[[WebDriver], bool]: """An expectation for checking the current url. - url is the expected url, which must be an exact match returns True - if the url matches, false otherwise. + Parameters: + ---------- + url : str + The expected url, which must be an exact match. + + Returns: + ------- + boolean : True when the url matches, False otherwise. """ def _predicate(driver: WebDriver): @@ -128,10 +175,17 @@ def _predicate(driver: WebDriver): def url_changes(url: str) -> Callable[[WebDriver], bool]: - """An expectation for checking the current url. + """An expectation for checking the current url is different than a given + string. + + Parameters: + ---------- + url : str + The expected url, which must not be an exact match. - url is the expected url, which must not be an exact match returns - True if the url is different, false otherwise. + Returns: + ------- + boolean : True when the url does not match, False otherwise """ def _predicate(driver: WebDriver): @@ -147,8 +201,22 @@ def visibility_of_element_located( page and visible. Visibility means that the element is not only displayed but also has a height and width that is greater than 0. - locator - used to find the element - returns the WebElement once it is located and visible + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + + Returns: + ------- + WebElement : The WebElement once it is located and visible. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.visibility_of_element_located((By.NAME, "q"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -164,6 +232,25 @@ def visibility_of(element: WebElement) -> Callable[[Any], Union[Literal[False], """An expectation for checking that an element, known to be present on the DOM of a page, is visible. + Parameters: + ---------- + element : WebElement + The WebElement to check. + + Returns: + ------- + WebElement : The WebElement once it is visible. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.visibility_of(driver.find_element(By.NAME, "q"))) + + Notes: + ------ Visibility means that the element is not only displayed but also has a height and width that is greater than 0. element is the WebElement returns the (same) WebElement once it is visible @@ -176,6 +263,20 @@ def _predicate(_): def _element_if_visible(element: WebElement, visibility: bool = True) -> Union[Literal[False], WebElement]: + """An expectation for checking that an element, known to be present on the + DOM of a page, is of the expected visibility. + + Parameters: + ---------- + element : WebElement + The WebElement to check. + visibility : bool + The expected visibility of the element. + + Returns: + ------- + WebElement : The WebElement once it is visible or not visible. + """ return element if element.is_displayed() == visibility else False @@ -183,8 +284,22 @@ def presence_of_all_elements_located(locator: Tuple[str, str]) -> Callable[[WebD """An expectation for checking that there is at least one element present on a web page. - locator is used to find the element returns the list of WebElements - once they are located + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + + Returns: + ------- + List[WebElement] : The list of WebElements once they are located. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> elements = WebDriverWait(driver, 10).until( + ... EC.presence_of_all_elements_located((By.CLASS_NAME, "foo"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -197,8 +312,22 @@ def visibility_of_any_elements_located(locator: Tuple[str, str]) -> Callable[[We """An expectation for checking that there is at least one element visible on a web page. - locator is used to find the element returns the list of WebElements - once they are located + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + + Returns: + ------- + List[WebElement] : The list of WebElements once they are located and visible. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> elements = WebDriverWait(driver, 10).until( + ... EC.visibility_of_any_elements_located((By.CLASS_NAME, "foo"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -214,8 +343,22 @@ def visibility_of_all_elements_located( a page and visible. Visibility means that the elements are not only displayed but also has a height and width that is greater than 0. - locator - used to find the elements - returns the list of WebElements once they are located and visible + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the elements. + + Returns: + ------- + List[WebElement] : The list of WebElements once they are located and visible. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> elements = WebDriverWait(driver, 10).until( + ... EC.visibility_of_all_elements_located((By.CLASS_NAME, "foo"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -235,7 +378,24 @@ def text_to_be_present_in_element(locator: Tuple[str, str], text_: str) -> Calla """An expectation for checking if the given text is present in the specified element. - locator, text + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + text_ : str + The text to be present in the element. + + Returns: + ------- + boolean : True when the text is present, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_text_in_element = WebDriverWait(driver, 10).until( + ... EC.text_to_be_present_in_element((By.CLASS_NAME, "foo"), "bar")) """ def _predicate(driver: WebDriverOrWebElement): @@ -254,7 +414,24 @@ def text_to_be_present_in_element_value( """An expectation for checking if the given text is present in the element's value. - locator, text + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + text_ : str + The text to be present in the element's value. + + Returns: + ------- + boolean : True when the text is present, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_text_in_element_value = WebDriverWait(driver, 10).until( + ... EC.text_to_be_present_in_element_value((By.CLASS_NAME, "foo"), "bar")) """ def _predicate(driver: WebDriverOrWebElement): @@ -273,7 +450,27 @@ def text_to_be_present_in_element_attribute( """An expectation for checking if the given text is present in the element's attribute. - locator, attribute, text + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + attribute_ : str + The attribute to check the text in. + text_ : str + The text to be present in the element's attribute. + + Returns: + ------- + boolean : True when the text is present, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_text_in_element_attribute = WebDriverWait(driver, 10).until( + ... EC.text_to_be_present_in_element_attribute((By.CLASS_NAME, "foo"), + ... "bar", "baz")) """ def _predicate(driver: WebDriverOrWebElement): @@ -292,6 +489,24 @@ def frame_to_be_available_and_switch_to_it(locator: Union[Tuple[str, str], str]) """An expectation for checking whether the given frame is available to switch to. + Parameters: + ---------- + locator : Union[Tuple[str, str], str] + Used to find the frame. + + Returns: + ------- + boolean : True when the frame is available, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> WebDriverWait(driver, 10).until( + ... EC.frame_to_be_available_and_switch_to_it("frame_name")) + + Notes: + ------ If the frame is available it switches the given driver to the specified frame. """ @@ -315,7 +530,30 @@ def invisibility_of_element_located( """An Expectation for checking that an element is either invisible or not present on the DOM. - locator used to find the element + Parameters: + ---------- + locator : Union[WebElement, Tuple[str, str]] + Used to find the element. + + Returns: + ------- + boolean : True when the element is invisible or not present, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_invisible = WebDriverWait(driver, 10).until( + ... EC.invisibility_of_element_located((By.CLASS_NAME, "foo"))) + + Notes: + ------ + - In the case of NoSuchElement, returns true because the element is not + present in DOM. The try block checks if the element is present but is + invisible. + - In the case of StaleElementReference, returns true because stale element + reference implies that element is no longer visible. """ def _predicate(driver: WebDriverOrWebElement): @@ -341,7 +579,22 @@ def invisibility_of_element( """An Expectation for checking that an element is either invisible or not present on the DOM. - element is either a locator (text) or an WebElement + Parameters: + ---------- + element : Union[WebElement, Tuple[str, str]] + Used to find the element. + + Returns: + ------- + boolean : True when the element is invisible or not present, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_invisible_or_not_present = WebDriverWait(driver, 10).until( + ... EC.invisibility_of_element(driver.find_element(By.CLASS_NAME, "foo"))) """ return invisibility_of_element_located(element) @@ -352,7 +605,22 @@ def element_to_be_clickable( """An Expectation for checking an element is visible and enabled such that you can click it. - element is either a locator (text) or an WebElement + Parameters: + ---------- + mark : Union[WebElement, Tuple[str, str]] + Used to find the element. + + Returns: + ------- + WebElement : The WebElement once it is located and clickable. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.element_to_be_clickable((By.CLASS_NAME, "foo"))) """ # renamed argument to 'mark', to indicate that both locator @@ -372,8 +640,22 @@ def _predicate(driver: WebDriverOrWebElement): def staleness_of(element: WebElement) -> Callable[[Any], bool]: """Wait until an element is no longer attached to the DOM. - element is the element to wait for. returns False if the element is - still attached to the DOM, true otherwise. + Parameters: + ---------- + element : WebElement + The element to wait for. + + Returns: + ------- + boolean : False if the element is still attached to the DOM, true otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_element_stale = WebDriverWait(driver, 10).until( + ... EC.staleness_of(driver.find_element(By.CLASS_NAME, "foo"))) """ def _predicate(_): @@ -390,7 +672,22 @@ def _predicate(_): def element_to_be_selected(element: WebElement) -> Callable[[Any], bool]: """An expectation for checking the selection is selected. - element is WebElement object + Parameters: + ---------- + element : WebElement + The WebElement to check. + + Returns: + ------- + boolean : True if the element is selected, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_selected = WebDriverWait(driver, 10).until( + ... EC.element_to_be_selected(driver.find_element(By.CLASS_NAME, "foo"))) """ def _predicate(_): @@ -402,7 +699,22 @@ def _predicate(_): def element_located_to_be_selected(locator: Tuple[str, str]) -> Callable[[WebDriverOrWebElement], bool]: """An expectation for the element to be located is selected. - locator is a tuple of (by, path) + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + + Returns: + ------- + boolean : True if the element is selected, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_selected = WebDriverWait(driver, 10).until( + ... EC.element_located_to_be_selected((By.CLASS_NAME, "foo"))) """ def _predicate(driver: WebDriverOrWebElement): @@ -414,7 +726,23 @@ def _predicate(driver: WebDriverOrWebElement): def element_selection_state_to_be(element: WebElement, is_selected: bool) -> Callable[[Any], bool]: """An expectation for checking if the given element is selected. - element is WebElement object is_selected is a Boolean. + Parameters: + ---------- + element : WebElement + The WebElement to check. + is_selected : bool + + Returns: + ------- + boolean : True if the element's selection state is the same as is_selected + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_selected = WebDriverWait(driver, 10).until( + ... EC.element_selection_state_to_be(driver.find_element(By.CLASS_NAME, "foo"), True)) """ def _predicate(_): @@ -429,7 +757,23 @@ def element_located_selection_state_to_be( """An expectation to locate an element and check if the selection state specified is in that state. - locator is a tuple of (by, path) is_selected is a boolean + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + is_selected : bool + + Returns: + ------- + boolean : True if the element's selection state is the same as is_selected + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_selected = WebDriverWait(driver, 10).until( + ... EC.element_located_selection_state_to_be((By.CLASS_NAME, "foo"), True)) """ def _predicate(driver: WebDriverOrWebElement): @@ -443,7 +787,24 @@ def _predicate(driver: WebDriverOrWebElement): def number_of_windows_to_be(num_windows: int) -> Callable[[WebDriver], bool]: - """An expectation for the number of windows to be a certain value.""" + """An expectation for the number of windows to be a certain value. + + Parameters: + ---------- + num_windows : int + The expected number of windows. + + Returns: + ------- + boolean : True when the number of windows matches, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_number_of_windows = WebDriverWait(driver, 10).until( + ... EC.number_of_windows_to_be(2)) + """ def _predicate(driver: WebDriver): return len(driver.window_handles) == num_windows @@ -453,7 +814,25 @@ def _predicate(driver: WebDriver): def new_window_is_opened(current_handles: List[str]) -> Callable[[WebDriver], bool]: """An expectation that a new window will be opened and have the number of - windows handles increase.""" + windows handles increase. + + Parameters: + ---------- + current_handles : List[str] + The current window handles. + + Returns: + ------- + boolean : True when a new window is opened, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.support.ui import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_new_window_opened = WebDriverWait(driver, 10).until( + ... EC.new_window_is_opened(driver.window_handles)) + """ def _predicate(driver: WebDriver): return len(driver.window_handles) > len(current_handles) @@ -463,7 +842,22 @@ def _predicate(driver: WebDriver): def alert_is_present() -> Callable[[WebDriver], Union[Alert, Literal[False]]]: """An expectation for checking if an alert is currently present and - switching to it.""" + switching to it. + + Returns: + ------- + Alert : The Alert once it is located. + + Example: + -------- + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> alert = WebDriverWait(driver, 10).until(EC.alert_is_present()) + + Notes: + ------ + If the alert is present it switches the given driver to it. + """ def _predicate(driver: WebDriver): try: @@ -478,7 +872,24 @@ def element_attribute_to_include(locator: Tuple[str, str], attribute_: str) -> C """An expectation for checking if the given attribute is included in the specified element. - locator, attribute + Parameters: + ---------- + locator : Tuple[str, str] + Used to find the element. + attribute_ : str + The attribute to check. + + Returns: + ------- + boolean : True when the attribute is included, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> is_attribute_in_element = WebDriverWait(driver, 10).until( + ... EC.element_attribute_to_include((By.CLASS_NAME, "foo"), "bar")) """ def _predicate(driver: WebDriverOrWebElement): @@ -494,6 +905,26 @@ def _predicate(driver: WebDriverOrWebElement): def any_of(*expected_conditions: Callable[[D], T]) -> Callable[[D], Union[Literal[False], T]]: """An expectation that any of multiple expected conditions is true. + Parameters: + ---------- + expected_conditions : Callable[[D], T] + The list of expected conditions to check. + + Returns: + ------- + T : The result of the first matching condition, or False if none do. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.any_of(EC.presence_of_element_located((By.NAME, "q"), + ... EC.visibility_of_element_located((By.NAME, "q")))) + + Notes: + ------ Equivalent to a logical 'OR'. Returns results of the first matching condition, or False if none do. """ @@ -516,6 +947,26 @@ def all_of( ) -> Callable[[D], Union[List[T], Literal[False]]]: """An expectation that all of multiple expected conditions is true. + Parameters: + ---------- + expected_conditions : Callable[[D], Union[T, Literal[False]]] + The list of expected conditions to check. + + Returns: + ------- + List[T] : The results of all the matching conditions, or False if any do not. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> elements = WebDriverWait(driver, 10).until( + ... EC.all_of(EC.presence_of_element_located((By.NAME, "q"), + ... EC.visibility_of_element_located((By.NAME, "q")))) + + Notes: + ------ Equivalent to a logical 'AND'. Returns: When any ExpectedCondition is not met: False. When all ExpectedConditions are met: A List with each ExpectedCondition's return value. @@ -539,6 +990,26 @@ def all_of_condition(driver: D): def none_of(*expected_conditions: Callable[[D], Any]) -> Callable[[D], bool]: """An expectation that none of 1 or multiple expected conditions is true. + Parameters: + ---------- + expected_conditions : Callable[[D], Any] + The list of expected conditions to check. + + Returns: + ------- + boolean : True if none of the conditions are true, False otherwise. + + Example: + -------- + >>> from selenium.webdriver.common.by import By + >>> from selenium.webdriver.support.ui import WebDriverWait + >>> from selenium.webdriver.support import expected_conditions as EC + >>> element = WebDriverWait(driver, 10).until( + ... EC.none_of(EC.presence_of_element_located((By.NAME, "q"), + ... EC.visibility_of_element_located((By.NAME, "q")))) + + Notes: + ------ Equivalent to a logical 'NOT-OR'. Returns a Boolean """