robo_appian 0.0.27__py3-none-any.whl → 0.0.34__py3-none-any.whl

robo_appian/components/InputUtils.py

@@ -2,19 +2,38 @@ from robo_appian.utils.ComponentUtils import ComponentUtils
 from selenium.webdriver.support import expected_conditions as EC
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.remote.webelement import WebElement
+from selenium.webdriver.common.action_chains import ActionChains
 
 
 class InputUtils:
     """
-    Utility class for interacting with input components in Appian UI.
-    Usage Example:
-        from robo_appian.components.InputUtils import InputUtils
+    Fill text inputs, search fields, and other input components using label-driven selectors.
 
-        # Set a value in an input component by its label
-        InputUtils.setValueByLabelText(wait, "Username", "test_user")
+    This utility handles text inputs by their visible labels, making tests readable and maintainable.
+    Automatically waits for clickability, clears existing values, and enters new text.
 
-        # Set a value in an input component by its ID
-        InputUtils.setValueById(wait, "inputComponentId", "test_value")
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian import InputUtils
+
+        # Set value by exact label match
+        InputUtils.setValueByLabelText(wait, "Username", "john_doe")
+        InputUtils.setValueByLabelText(wait, "Email Address", "john@example.com")
+
+        # Set value by partial label match (useful for dynamic labels)
+        InputUtils.setValueByPartialLabelText(wait, "First", "John")
+
+        # Set value by element ID
+        InputUtils.setValueById(wait, "email_input_123", "john@example.com")
+
+        # Set value by placeholder text
+        InputUtils.setValueByPlaceholderText(wait, "Enter your name", "John Doe")
+
+    Note:
+        - Uses normalize-space and NBSP translation to handle whitespace variations
+        - Automatically moves to element, clears it, and enters text via ActionChains
+        - Waits for element to be clickable before interacting
     """
 
     @staticmethod
@@ -38,7 +57,9 @@ class InputUtils:
 
         input_id = label_component.get_attribute("for")
         if input_id is None:
-            raise ValueError(f"Label component with text '{label}' does not have a 'for' attribute.")
+            raise ValueError(
+                f"Label component with text '{label}' does not have a 'for' attribute."
+            )
 
         component = ComponentUtils.findComponentById(wait, input_id)
         return component
@@ -61,7 +82,9 @@ class InputUtils:
         label_component = ComponentUtils.waitForComponentToBeVisibleByXpath(wait, xpath)
         input_id = label_component.get_attribute("for")
         if input_id is None:
-            raise ValueError(f"Label component with text '{label}' does not have a 'for' attribute.")
+            raise ValueError(
+                f"Label component with text '{label}' does not have a 'for' attribute."
+            )
 
         component = ComponentUtils.findComponentById(wait, input_id)
         return component
@@ -71,14 +94,17 @@ class InputUtils:
         """
         Sets a value in an input component.
         Parameters:
+            wait: Selenium WebDriverWait instance.
             component: The Selenium WebElement for the input component.
             value: The value to set in the input field.
         Returns:
             The Selenium WebElement for the input component after setting the value.
         Example:
-            InputUtils._setValueByComponent(component, "test_value")
+            InputUtils._setValueByComponent(wait, component, "test_value")
         """
         wait.until(EC.element_to_be_clickable(component))
+        driver = wait._driver
+        ActionChains(driver).move_to_element(component).perform()
         component.clear()
         component.send_keys(value)
         return component
@@ -102,18 +128,24 @@ class InputUtils:
     @staticmethod
     def setValueByLabelText(wait: WebDriverWait, label: str, value: str):
         """
-        Sets a value in an input component identified by its label text.
+        Set value in an input field by its exact label text.
 
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the input component.
-            value: The value to set in the input field.
+        Finds the input by its associated label, waits for clickability, clears any existing
+        text, and enters the new value. Most commonly used method for form filling.
 
-        Returns:
-            None
+        Args:
+            wait: WebDriverWait instance (required by all robo_appian utilities).
+            label: Exact visible label text. Must match exactly (e.g., "First Name", not "First").
+            value: Text to enter into the input field.
 
-        Example:
-            InputUtils.setValueByLabelText(wait, "Username", "test_user")
+        Raises:
+            ValueError: If label element has no 'for' attribute linking to input.
+            TimeoutException: If label or input not found within wait timeout.
+
+        Examples:
+            >>> InputUtils.setValueByLabelText(wait, "Username", "john_doe")
+            >>> InputUtils.setValueByLabelText(wait, "Email", "john@example.com")
+            >>> InputUtils.setValueByLabelText(wait, "Address", "123 Main St")
         """
         component = InputUtils.__findComponentByLabel(wait, label)
         InputUtils._setValueByComponent(wait, component, value)

robo_appian/components/LabelUtils.py

@@ -6,50 +6,89 @@ from robo_appian.utils.ComponentUtils import ComponentUtils
 
 class LabelUtils:
     """
-    Utility class for interacting with label components in Appian UI.
-    Usage Example:
-        # Find a label by its text
-        component = LabelUtils._findByLabelText(wait, "Submit")
-        # Click a label by its text
-        LabelUtils.clickByLabelText(wait, "Submit")
+    Find and click text labels and headings in Appian UI.
+
+    Use these utilities to check for the presence of labels, headers, or other text elements
+    that don't fit into form component categories. Useful for validation steps that verify
+    page content or labels before/after actions.
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian import LabelUtils
+        >>> LabelUtils.clickByLabelText(wait, "Expand")
+        >>> if LabelUtils.isLabelExists(wait, "Success!"):
+        ...     print("Operation completed")
+
+    Note:
+        - Handles NBSP characters automatically via normalize-space
+        - Supports existence checks for validation and assertions
+        - Useful in test assertions: `assert LabelUtils.isLabelExists(wait, "Pending")`
     """
 
     @staticmethod
     def __findByLabelText(wait: WebDriverWait, label: str):
         """
-        Finds a label element by its text.
+        Find a label element by exact text (internal helper).
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text of the label.
+
+        Returns:
+            WebElement: The label element.
 
-        :param wait: Selenium WebDriverWait instance.
-        :param label: The text of the label to find.
-        :return: WebElement representing the label.
-        Example:
-            component = LabelUtils._findByLabelText(wait, "Submit")
+        Raises:
+            TimeoutException: If label not found within timeout.
         """
         xpath = f'//*[normalize-space(translate(., "\u00a0", " "))="{label}"]'
-        try:
-            # component = wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
-            component = ComponentUtils.waitForComponentToBeVisibleByXpath(wait, xpath)
-        except Exception as e:
-            raise Exception(f"Label with text '{label}' not found.") from e
-
+        component = ComponentUtils.waitForComponentToBeVisibleByXpath(wait, xpath)
         return component
 
     @staticmethod
     def clickByLabelText(wait: WebDriverWait, label: str):
         """
-        Clicks a label element identified by its text.
+        Click a label or text element by its exact visible text.
+
+        Find and click text elements that trigger UI changes (e.g., collapsible headers).
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text of the element to click.
+
+        Returns:
+            None
+
+        Raises:
+            TimeoutException: If element not found or not clickable within timeout.
 
-        :param wait: Selenium WebDriverWait instance.
-        :param label: The text of the label to click.
-        Example:
-            LabelUtils.clickByLabelText(wait, "Submit")
+        Examples:
+            >>> LabelUtils.clickByLabelText(wait, "Expand")
+            >>> LabelUtils.clickByLabelText(wait, "Show Details")
         """
         component = LabelUtils.__findByLabelText(wait, label)
-        wait.until(EC.element_to_be_clickable(component))
-        component.click()
+        ComponentUtils.click(wait, component)
 
     @staticmethod
     def isLabelExists(wait: WebDriverWait, label: str):
+        """
+        Check if a label with the exact text exists on the page.
+
+        Non-blocking check useful in test assertions and conditional logic.
+        Returns False if label not found or times out (doesn't raise exception).
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text to search for.
+
+        Returns:
+            bool: True if label found and visible, False otherwise.
+
+        Examples:
+            >>> if LabelUtils.isLabelExists(wait, "Error: Invalid input"):
+            ...     print("Validation error displayed")
+            >>> assert LabelUtils.isLabelExists(wait, "Success!"), "Success message not found"
+        """
         try:
             LabelUtils.__findByLabelText(wait, label)
         except Exception:
@@ -58,9 +97,26 @@ class LabelUtils:
 
     @staticmethod
     def isLabelExistsAfterLoad(wait: WebDriverWait, label: str):
+        """
+        Check if a label exists after waiting for visibility (stricter validation).
+
+        Waits explicitly for the element to become visible, unlike isLabelExists which
+        may find invisible elements. Use this when page is still loading.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text to search for.
+
+        Returns:
+            bool: True if label becomes visible within timeout, False otherwise.
+
+        Examples:
+            >>> # Wait for success message to appear after form submission
+            >>> if LabelUtils.isLabelExistsAfterLoad(wait, "Saved successfully"):
+            ...     print("Form saved")
+        """
         try:
             xpath = f'.//*[normalize-space(translate(., "\u00a0", " "))="{label}"]'
-            wait.until(EC.presence_of_element_located((By.XPATH, xpath)))
             wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
         except Exception:
             return False

robo_appian/components/LinkUtils.py

@@ -1,46 +1,81 @@
 from selenium.webdriver.common.by import By
 from selenium.webdriver.support import expected_conditions as EC
 from selenium.webdriver.support.ui import WebDriverWait
+from robo_appian.utils.ComponentUtils import ComponentUtils
 
 
 class LinkUtils:
     """
-    Utility class for handling link operations in Selenium WebDriver.
-    Example usage:
-        from selenium import webdriver
-        from selenium.webdriver.support.ui import WebDriverWait
-        from robo_appian.components.LinkUtils import LinkUtils
-
-        driver = webdriver.Chrome()
-        wait = WebDriverWait(driver, 10)
-        LinkUtils.click(wait, "Learn More")
-        driver.quit()
+    Click hyperlinks in Appian UI by their visible text.
+
+    Find and click links using their user-visible text label. Automatically waits for
+    clickability and handles hidden/overlay states. Uses ActionChains for reliable clicking
+    even when links are covered by animations or tooltips.
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian import LinkUtils
+        >>> LinkUtils.click(wait, "Learn More")
+        >>> LinkUtils.click(wait, "Edit Details")
+        >>> link = LinkUtils.find(wait, "View Report")
+
+    Note:
+        - Uses exact text matching for link discovery
+        - Excludes hidden links (aria-hidden="true") automatically
+        - Returns the link element (WebElement) for advanced use cases
     """
 
     @staticmethod
     def find(wait: WebDriverWait, label: str):
-        # xpath = f'.//a[normalize-space(.)="{label}"]'
+        """
+        Find a link element by its visible text.
+
+        Locates the first link that matches the exact text, excluding hidden links.
+        Useful when you need to inspect or chain operations on a link.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text of the link.
+
+        Returns:
+            WebElement: The link element (for advanced chaining).
+
+        Raises:
+            TimeoutException: If link not found within timeout.
+
+        Examples:
+            >>> link = LinkUtils.find(wait, "Edit")
+            >>> link.get_attribute("href")  # Get link URL
+        """
         xpath = f'.//a[normalize-space(.)="{label}" and not(ancestor::*[@aria-hidden="true"])]'
-        try:
-            component = wait.until(EC.presence_of_element_located((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Could not find clickable link with label '{label}': {e}")
+        component = wait.until(EC.presence_of_element_located((By.XPATH, xpath)))
         return component
 
     @staticmethod
     def click(wait: WebDriverWait, label: str):
         """
-        Clicks a link identified by its label.
+        Click a link by its exact visible text.
+
+        Finds the link by exact text match, waits for clickability, and clicks it using
+        ActionChains for reliable interaction even with animations or overlays.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible text of the link to click (e.g., "Edit", "Learn More").
+
+        Returns:
+            WebElement: The link element that was clicked.
 
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the link.
+        Raises:
+            TimeoutException: If link not found or not clickable within timeout.
 
-        Example:
-            LinkUtils.click(wait, "Learn More")
+        Examples:
+            >>> LinkUtils.click(wait, "Learn More")
+            >>> LinkUtils.click(wait, "View Details")
+            >>> LinkUtils.click(wait, "Delete")
         """
 
         component = LinkUtils.find(wait, label)
-        wait.until(EC.element_to_be_clickable(component))
-        component.click()
+        ComponentUtils.click(wait, component)
         return component

robo_appian/components/SearchDropdownUtils.py

@@ -1,91 +1,145 @@
+from robo_appian.components.InputUtils import InputUtils
+from robo_appian.utils.ComponentUtils import ComponentUtils
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.support import expected_conditions as EC
 from selenium.webdriver.common.by import By
 from selenium.webdriver.remote.webelement import WebElement
-from robo_appian.components.InputUtils import InputUtils
 
 
 class SearchDropdownUtils:
     """
-    Utility class for interacting with search dropdown components in Appian UI.
-    Usage Example:
-        # Select a value from a search dropdown
-        from robo_appian.components.SearchDropdownUtils import SearchDropdownUtils
-        SearchDropdownUtils.selectSearchDropdownValueByLabelText(wait, "Status", "Approved")
+    Select values from search-enabled dropdowns in Appian UI.
+
+    Search dropdowns allow users to type to filter options, then click to select. These differ
+    from standard dropdowns because they include a search/filter input field. Automatically
+    types the search term, waits for options to populate, and clicks the matching option.
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian import SearchDropdownUtils
+        >>> # Select by exact label match
+        >>> SearchDropdownUtils.selectSearchDropdownValueByLabelText(wait, "Employee", "John Doe")
+        >>> # Select by partial label match
+        >>> SearchDropdownUtils.selectSearchDropdownValueByPartialLabelText(wait, "Status", "Approved")
+
+    Note:
+        - Search dropdowns use the combobox ARIA pattern with ID-based suffixes (`_searchInput`, `_list`)
+        - Component lookup by label is more reliable than searching by ID directly
+        - Automatically waits for dropdown options to appear after typing search term
     """
 
     @staticmethod
-    def __selectSearchDropdownValueByDropdownId(wait: WebDriverWait, component_id: str, value: str):
+    def __selectSearchDropdownValueByDropdownId(
+        wait: WebDriverWait, component_id: str, value: str
+    ):
         if not component_id:
             raise ValueError("Invalid component_id provided.")
 
         input_component_id = str(component_id) + "_searchInput"
-        try:
-            wait.until(EC.presence_of_element_located((By.ID, input_component_id)))
-            input_component = wait.until(EC.element_to_be_clickable((By.ID, input_component_id)))
-        except Exception as e:
-            raise Exception(f"Failed to locate or click input component with ID '{input_component_id}': {e}")
+        input_component = wait.until(
+            EC.element_to_be_clickable((By.ID, input_component_id))
+        )
         InputUtils._setValueByComponent(wait, input_component, value)
 
         dropdown_option_id = str(component_id) + "_list"
 
         xpath = f'.//ul[@id="{dropdown_option_id}"]/li[./div[normalize-space(.)="{value}"]][1]'
-        try:
-            component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Failed to locate or click dropdown option with XPath '{xpath}': {e}")
-        component.click()
+        component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
+        ComponentUtils.click(wait, component)
 
     @staticmethod
-    def __selectSearchDropdownValueByPartialLabelText(wait: WebDriverWait, label: str, value: str):
+    def __selectSearchDropdownValueByPartialLabelText(
+        wait: WebDriverWait, label: str, value: str
+    ):
         xpath = f'.//div[./div/span[contains(normalize-space(.), "{label}")]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'
-        try:
-            combobox = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Failed to locate or click dropdown component with XPath '{xpath}': {e}")
+        combobox = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
 
-        SearchDropdownUtils._selectSearchDropdownValueByComboboxComponent(wait, combobox, value)
+        SearchDropdownUtils._selectSearchDropdownValueByComboboxComponent(
+            wait, combobox, value
+        )
 
     @staticmethod
-    def __selectSearchDropdownValueByLabelText(wait: WebDriverWait, label: str, value: str):
-        xpath = (
-            f'.//div[./div/span[normalize-space(.)="{label}"]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'
+    def __selectSearchDropdownValueByLabelText(
+        wait: WebDriverWait, label: str, value: str
+    ):
+        xpath = f'.//div[./div/span[normalize-space(.)="{label}"]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'
+        combobox = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
+        SearchDropdownUtils._selectSearchDropdownValueByComboboxComponent(
+            wait, combobox, value
         )
-        try:
-            combobox = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Failed to locate or click dropdown component with XPath '{xpath}': {e}")
-        SearchDropdownUtils._selectSearchDropdownValueByComboboxComponent(wait, combobox, value)
 
     @staticmethod
-    def _selectSearchDropdownValueByComboboxComponent(wait: WebDriverWait, combobox: WebElement, value: str):
+    def _selectSearchDropdownValueByComboboxComponent(
+        wait: WebDriverWait, combobox: WebElement, value: str
+    ):
         id = combobox.get_attribute("id")
         if id is not None:
             component_id = id.rsplit("_value", 1)[0]
         else:
             raise Exception("Combobox element does not have an 'id' attribute.")
 
-        wait.until(EC.element_to_be_clickable(combobox))
-        combobox.click()
+        ComponentUtils.click(wait, combobox)
 
-        SearchDropdownUtils.__selectSearchDropdownValueByDropdownId(wait, component_id, value)
+        SearchDropdownUtils.__selectSearchDropdownValueByDropdownId(
+            wait, component_id, value
+        )
 
     @staticmethod
-    def selectSearchDropdownValueByLabelText(wait: WebDriverWait, dropdown_label: str, value: str):
-        """Selects a value from a search dropdown by label text.
+    def selectSearchDropdownValueByLabelText(
+        wait: WebDriverWait, dropdown_label: str, value: str
+    ):
+        """
+        Select a value from a search dropdown using exact label match.
+
+        Types the value into the search field, waits for filtered options to appear,
+        then clicks the matching option.
+
         Args:
-            wait (WebDriverWait): The WebDriverWait instance to use for waiting.
-            dropdown_label (str): The label text of the dropdown.
-            value (str): The value to select from the dropdown.
+            wait: WebDriverWait instance.
+            dropdown_label: Exact visible label text of the dropdown (e.g., "Employee").
+            value: Exact text of the option to select (e.g., "John Doe").
+
+        Returns:
+            None
+
+        Raises:
+            TimeoutException: If dropdown or option not found within timeout.
+            ValueError: If dropdown ID cannot be extracted from element.
+
+        Examples:
+            >>> SearchDropdownUtils.selectSearchDropdownValueByLabelText(wait, "Employee", "John Doe")
+            >>> SearchDropdownUtils.selectSearchDropdownValueByLabelText(wait, "Status", "Approved")
         """
-        SearchDropdownUtils.__selectSearchDropdownValueByLabelText(wait, dropdown_label, value)
+        SearchDropdownUtils.__selectSearchDropdownValueByLabelText(
+            wait, dropdown_label, value
+        )
 
     @staticmethod
-    def selectSearchDropdownValueByPartialLabelText(wait: WebDriverWait, dropdown_label: str, value: str):
-        """Selects a value from a search dropdown by partial label text.
+    def selectSearchDropdownValueByPartialLabelText(
+        wait: WebDriverWait, dropdown_label: str, value: str
+    ):
+        """
+        Select a value from a search dropdown using partial label match.
+
+        Useful when the dropdown label contains dynamic text (e.g., includes a count or suffix).
+        Searches for the label using a contains check instead of exact match.
+
         Args:
-            wait (WebDriverWait): The WebDriverWait instance to use for waiting.
-            dropdown_label (str): The label text of the dropdown.
-            value (str): The value to select from the dropdown.
+            wait: WebDriverWait instance.
+            dropdown_label: Partial visible label text (uses contains matching).
+            value: Exact text of the option to select.
+
+        Returns:
+            None
+
+        Raises:
+            TimeoutException: If dropdown or option not found within timeout.
+            ValueError: If dropdown ID cannot be extracted from element.
+
+        Examples:
+            >>> SearchDropdownUtils.selectSearchDropdownValueByPartialLabelText(wait, "Employee", "John")
         """
-        SearchDropdownUtils.__selectSearchDropdownValueByPartialLabelText(wait, dropdown_label, value)
+        SearchDropdownUtils.__selectSearchDropdownValueByPartialLabelText(
+            wait, dropdown_label, value
+        )