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

robo_appian/components/SearchInputUtils.py

@@ -1,63 +1,109 @@
 from selenium.webdriver.support.ui import WebDriverWait
-from selenium.webdriver.common.by import By
-from selenium.webdriver.support import expected_conditions as EC
 from robo_appian.components.InputUtils import InputUtils
 from robo_appian.utils.ComponentUtils import ComponentUtils
 
 
 class SearchInputUtils:
     """
-    Utility class for handling search input operations in Selenium WebDriver.
-    Example usage:
-        from selenium import webdriver
-        from selenium.webdriver.support.ui import WebDriverWait
-        from robo_appian.components.SearchInputUtils import SearchInputUtils
-
-        driver = webdriver.Chrome()
-        wait = WebDriverWait(driver, 10)
-        SearchInputUtils.selectSearchDropdownByLabelText(wait, "Search Label", "Value")
-        driver.quit()
+    Search and select from searchable input components in Appian UI.
+
+    Similar to SearchDropdownUtils, but for input components that support filtering/search.
+    Finds the input by label, types a search term, waits for matching options in a dropdown list,
+    and selects the option.
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian import SearchInputUtils
+        >>> # Select by exact label match
+        >>> SearchInputUtils.selectSearchDropdownByLabelText(wait, "Employee Name", "John Doe")
+        >>> # Select by partial label match
+        >>> SearchInputUtils.selectSearchDropdownByPartialLabelText(wait, "Employee", "John")
+
+    Note:
+        - Searchable inputs often appear in Appian forms for employee/user selection
+        - Uses ARIA combobox and listbox patterns for element discovery
+        - Waits for listbox options to populate after typing search term
     """
 
     @staticmethod
-    def __findSearchInputComponentsByLabelPathAndSelectValue(wait: WebDriverWait, xpath: str, value: str):
-        search_input_components = ComponentUtils.findComponentsByXPath(wait, xpath)
-        input_components = []
-        for search_input_component in search_input_components:
-            attribute: str = "aria-controls"
-            dropdown_list_id = search_input_component.get_attribute(attribute)
-            if dropdown_list_id:
-                InputUtils._setValueByComponent(wait, search_input_component, value)
-                xpath = f'.//ul[@id="{dropdown_list_id}" and @role="listbox" ]/li[@role="option" and @tabindex="-1" and ./div/div/div/div/div/div/p[normalize-space(.)="{value}"][1]]'
-                try:
-                    drop_down_item = wait.until(EC.presence_of_element_located((By.XPATH, xpath)))
-                    drop_down_item = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
-                except Exception as e:
-                    raise Exception(
-                        f"Dropdown item with value '{value}' not found for component '{search_input_component.text}'."
-                    ) from e
-                drop_down_item.click()
-            else:
-                raise ValueError(
-                    f"Search input component with label '{search_input_component.text}' does not have 'aria-controls' attribute."
-                )
-
-        return input_components
+    def __findSearchInputComponentsByLabelPathAndSelectValue(
+        wait: WebDriverWait, xpath: str, value: str
+    ):
+
+        search_input_component = ComponentUtils.waitForComponentToBeVisibleByXpath(
+            wait, xpath
+        )
+        attribute: str = "aria-controls"
+        dropdown_list_id = search_input_component.get_attribute(attribute)
+        if dropdown_list_id:
+            InputUtils._setValueByComponent(wait, search_input_component, value)
+            xpath = f'.//ul[@id="{dropdown_list_id}" and @role="listbox" ]/li[@role="option" and @tabindex="-1" and ./div/div/div/div/div/div/p[normalize-space(.)="{value}"][1]]'
+            drop_down_item = ComponentUtils.waitForComponentToBeVisibleByXpath(
+                wait, xpath
+            )
+            ComponentUtils.click(wait, drop_down_item)
+        else:
+            raise ValueError(
+                f"Search input component with label '{search_input_component.text}' does not have 'aria-controls' attribute."
+            )
+
+        return search_input_component
 
     @staticmethod
-    def __selectSearchInputComponentsByPartialLabelText(wait: WebDriverWait, label: str, value: str):
-        xpath = f".//div[./div/span[contains(normalize-space(.)='{label}']]/div/div/div/input[@role='combobox']"
-        SearchInputUtils.__findSearchInputComponentsByLabelPathAndSelectValue(wait, xpath, value)
+    def __selectSearchInputComponentsByPartialLabelText(
+        wait: WebDriverWait, label: str, value: str
+    ):
+        xpath = f'.//div[./div/span[contains(normalize-space(.)="{label}"]]/div/div/div/input[@role="combobox"]'
+        SearchInputUtils.__findSearchInputComponentsByLabelPathAndSelectValue(
+            wait, xpath, value
+        )
 
     @staticmethod
-    def __selectSearchInputComponentsByLabelText(wait: WebDriverWait, label: str, value: str):
-        xpath = f".//div[./div/span[text()='{label}']]/div/div/div/input[@role='combobox']"
-        SearchInputUtils.__findSearchInputComponentsByLabelPathAndSelectValue(wait, xpath, value)
+    def __selectSearchInputComponentsByLabelText(
+        wait: WebDriverWait, label: str, value: str
+    ):
+        xpath = f'.//div[./div/span[normalize-space(translate(., "\u00a0", " "))="{label}"]]/div/div/div/input[@role="combobox"]'
+        SearchInputUtils.__findSearchInputComponentsByLabelPathAndSelectValue(
+            wait, xpath, value
+        )
 
     @staticmethod
     def selectSearchDropdownByLabelText(wait: WebDriverWait, label: str, value: str):
+        """
+        Select a value from a search input using exact label match.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible label text of the search input.
+            value: Exact text of the option to select from the dropdown.
+
+        Returns:
+            None
+
+        Examples:
+            >>> SearchInputUtils.selectSearchDropdownByLabelText(wait, "Employee Name", "John Doe")
+        """
         SearchInputUtils.__selectSearchInputComponentsByLabelText(wait, label, value)
 
     @staticmethod
-    def selectSearchDropdownByPartialLabelText(wait: WebDriverWait, label: str, value: str):
-        SearchInputUtils.__selectSearchInputComponentsByPartialLabelText(wait, label, value)
+    def selectSearchDropdownByPartialLabelText(
+        wait: WebDriverWait, label: str, value: str
+    ):
+        """
+        Select a value from a search input using partial label match.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Partial visible label text (uses contains matching).
+            value: Exact text of the option to select from the dropdown.
+
+        Returns:
+            None
+
+        Examples:
+            >>> SearchInputUtils.selectSearchDropdownByPartialLabelText(wait, "Employee", "John")
+        """
+        SearchInputUtils.__selectSearchInputComponentsByPartialLabelText(
+            wait, label, value
+        )

robo_appian/components/TabUtils.py

@@ -7,47 +7,94 @@ from robo_appian.utils.ComponentUtils import ComponentUtils
 
 class TabUtils:
     """
-    Utility class for handling tab components in a web application using Selenium.
-    Example usage:
-        from selenium import webdriver
-        from selenium.webdriver.support.ui import WebDriverWait
-        from robo_appian.components.TabUtils import TabUtils
+    Select and check tab components in Appian UI.
 
-        driver = webdriver.Chrome()
-        wait = WebDriverWait(driver, 10)
+    Find and click tabs to navigate between sections within a single page. Appian often uses
+    tabs to organize related content. Automatically waits for clickability and uses ActionChains
+    for reliable interaction.
 
-        # Find a selected tab by its label
-        selected_tab = TabUtils.findSelectedTabByLabelText(wait, "Tab Label")
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
 
-        # Select an inactive tab by its label
-        TabUtils.selectTabByLabelText(wait, "Inactive Tab Label")
+    Examples:
+        >>> from robo_appian import TabUtils
+        >>> TabUtils.selectTabByLabelText(wait, "Details")  # Click a tab
+        >>> tab = TabUtils.findTabByLabelText(wait, "History")  # Get tab element
+        >>> is_selected = TabUtils.checkTabSelectedByLabelText(wait, "Active")  # Check state
 
-        driver.quit()
+    Note:
+        - Tab navigation triggers content reloads; be ready to wait for new elements
+        - Tab labels are stored in nested divs with role="link" and semantic text
     """
-    @staticmethod
-    def __click(wait: WebDriverWait, component: WebElement, label: str):
-        try:
-            component = wait.until(EC.element_to_be_clickable(component))
-            component.click()
-        except Exception:
-            raise Exception(f"Tab with label '{label}' is not clickable.")
 
     @staticmethod
     def findTabByLabelText(wait: WebDriverWait, label: str) -> WebElement:
+        """
+        Find a tab element by its exact visible label.
+
+        Returns the tab element (useful for chaining or advanced inspection).
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible label text of the tab (e.g., "Details", "History").
+
+        Returns:
+            WebElement: The tab element.
+
+        Raises:
+            TimeoutException: If tab not found within timeout.
+
+        Examples:
+            >>> tab = TabUtils.findTabByLabelText(wait, "Details")
+        """
         xpath = f'//div/div[@role="link" ]/div/div/div/div/div/p[normalize-space(.)="{label}"]'
-        try:
-            component = wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
-        except Exception:
-            raise Exception(f"Tab with label '{label}' not found.")
+        component = wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
         return component
 
     @staticmethod
     def selectTabByLabelText(wait: WebDriverWait, label: str):
+        """
+        Click a tab to navigate to it by its exact visible label.
+
+        Finds and clicks the tab. After clicking, content in the tab panel will load;
+        be ready to wait for elements within the new tab.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible label text of the tab to select.
+
+        Returns:
+            None
+
+        Raises:
+            TimeoutException: If tab not found or not clickable within timeout.
+
+        Examples:
+            >>> TabUtils.selectTabByLabelText(wait, "Details")
+            >>> TabUtils.selectTabByLabelText(wait, "History")
+        """
         component = TabUtils.findTabByLabelText(wait, label)
-        TabUtils.__click(wait, component, label)
+        ComponentUtils.click(wait, component)
 
     @staticmethod
     def checkTabSelectedByLabelText(wait: WebDriverWait, label: str):
+        """
+        Check if a tab is currently selected (active).
+
+        Returns True if the tab has the "Selected Tab" indicator (aria-label or span text),
+        False otherwise. Useful in test assertions to verify navigation.
+
+        Args:
+            wait: WebDriverWait instance.
+            label: Exact visible label text of the tab to check.
+
+        Returns:
+            bool: True if tab is selected, False otherwise (or if tab not found).
+
+        Examples:
+            >>> if TabUtils.checkTabSelectedByLabelText(wait, "Details"):
+            ...     print("Details tab is active")
+            >>> assert TabUtils.checkTabSelectedByLabelText(wait, "History"), "History tab should be selected"
+        """
         component = TabUtils.findTabByLabelText(wait, label)
 
         select_text = "Selected Tab."

robo_appian/components/TableUtils.py

@@ -6,38 +6,42 @@ from robo_appian.utils.ComponentUtils import ComponentUtils
 
 class TableUtils:
     """
-    Utility class for handling table operations in Selenium WebDriver.
-    Example usage:
-        from selenium import webdriver
-        from selenium.webdriver.support.ui import WebDriverWait
-        from robo_appian.components.TableUtils import TableUtils
-
-        driver = webdriver.Chrome()
-        wait = WebDriverWait(driver, 10)
-        table = TableUtils.findTableByColumnName(wait, "Status")
+    Interact with Appian grid/table components: read cells, click rows, find elements.
+
+    Query and interact with table rows and cells using column names as locators.
+    Automatically handles row/column indexing, finding cells by their position, and
+    interacting with components within cells (buttons, links, inputs).
+
+    Key concepts:
+        - Columns are identified by their header 'abbr' (abbreviation) attribute
+        - Rows are 0-based in public APIs (first row = 0)
+        - Rows are internally 1-indexed in Appian's data-dnd-name (conversion is automatic)
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian.components.TableUtils import TableUtils
+        >>> from selenium.webdriver.support.ui import WebDriverWait
+
+        # Find a table by column name and count rows
+        table = TableUtils.findTableByColumnName(wait, "Employee ID")
         row_count = TableUtils.rowCount(table)
-        component = TableUtils.findComponentFromTableCell(wait, 1, "Status")
-        driver.quit()
+        print(f"Table has {row_count} rows")
 
-    """
+        # Find and click component in specific cell (row 0, column "Status")
+        TableUtils.selectRowFromTableByColumnNameAndRowNumber(wait, 0, "Employee ID")
 
-    @staticmethod
-    def rowCount(tableObject):
-        """
-        Counts the number of rows in a table.
+        # Get a specific cell component
+        edit_button = TableUtils.findComponentFromTableCell(wait, 0, "Actions")
 
-        :param tableObject: The Selenium WebElement representing the table.
-        :return: The number of rows in the table.
-        Example:
-            row_count = TableUtils.rowCount(table)
-        """
+        # Interact with element in table cell
+        component = TableUtils.findComponentByColumnNameAndRowNumber(wait, 1, "Status")
 
-        xpath = "./tbody/tr[./td[not (@data-empty-grid-message)]]"
-        try:
-            rows = tableObject.find_elements(By.XPATH, xpath)
-        except Exception as e:
-            raise Exception(f"Could not count rows in table: {e}")
-        return len(rows)
+    Note:
+        - Tables are located by column header 'abbr' attribute
+        - Column positions are derived from header class attributes (e.g., "headCell_2")
+        - Hidden/aria-hidden elements are automatically excluded
+    """
 
     @staticmethod
     def __findColumNumberByColumnName(tableObject, columnName):
@@ -55,7 +59,9 @@ class TableUtils:
         component = tableObject.find_element(By.XPATH, xpath)
 
         if component is None:
-            raise ValueError(f"Could not find a column with abbr '{columnName}' in the table header.")
+            raise ValueError(
+                f"Could not find a column with abbr '{columnName}' in the table header."
+            )
 
         class_string = component.get_attribute("class")
         partial_string = "headCell_"
@@ -67,7 +73,9 @@ class TableUtils:
                 selected_word = word
 
         if selected_word is None:
-            raise ValueError(f"Could not find a class containing '{partial_string}' in the column header for '{columnName}'.")
+            raise ValueError(
+                f"Could not find a class containing '{partial_string}' in the column header for '{columnName}'."
+            )
 
         data = selected_word.split("_")
         return int(data[1])
@@ -97,17 +105,14 @@ class TableUtils:
         rowNumber = rowNumber + 1
         columnNumber = columnNumber + 1
         xpath = f'.//table[./thead/tr/th[@abbr="{columnName}"]]/tbody/tr[@data-dnd-name="row {rowNumber}"]/td[not (@data-empty-grid-message)][{columnNumber}]/*'
-        try:
-            component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Could not find component in cell at row {rowNumber}, column '{columnName}': {e}")
+        component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
         return component
 
     @staticmethod
     def selectRowFromTableByColumnNameAndRowNumber(wait, rowNumber, columnName):
         row = TableUtils.__findRowByColumnNameAndRowNumber(wait, rowNumber, columnName)
         row = wait.until(EC.element_to_be_clickable(row))
-        row.click()
+        ComponentUtils.click(wait, row)
 
     @staticmethod
     def findComponentByColumnNameAndRowNumber(wait, rowNumber, columnName):
@@ -118,7 +123,9 @@ class TableUtils:
         parts = id.rsplit("_", 1)
         columnNumber = int(parts[-1])
 
-        tableRow = TableUtils.__findRowByColumnNameAndRowNumber(wait, rowNumber, columnName)
+        tableRow = TableUtils.__findRowByColumnNameAndRowNumber(
+            wait, rowNumber, columnName
+        )
         xpath = f"./td[{columnNumber + 1}]/*"
         component = ComponentUtils.findChildComponentByXpath(wait, tableRow, xpath)
         component = wait.until(EC.element_to_be_clickable(component))
@@ -137,13 +144,30 @@ class TableUtils:
         """
 
         xpath = f'.//table[./thead/tr/th[@abbr="{columnName}"]]'
-        try:
-            component = wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
-        except Exception as e:
-            raise Exception(f"Could not find table with column name '{columnName}': {e}")
-
-        try:
-            component = wait.until(EC.element_to_be_clickable(component))
-        except Exception as e:
-            raise Exception(f"Table found by column name '{columnName}' is not clickable: {e}")
+        component = wait.until(EC.visibility_of_element_located((By.XPATH, xpath)))
+
+        component = wait.until(EC.element_to_be_clickable(component))
         return component
+
+    @staticmethod
+    def rowCount(tableObject):
+        """
+        Count non-empty rows in a table.
+
+        Returns the number of data rows (excluding empty grid message placeholders).
+
+        Args:
+            tableObject: WebElement representing the table (from findTableByColumnName).
+
+        Returns:
+            int: Number of rows in the table.
+
+        Examples:
+            >>> table = TableUtils.findTableByColumnName(wait, "Name")
+            >>> rows = TableUtils.rowCount(table)
+            >>> print(f"Found {rows} employees")
+        """
+
+        xpath = "./tbody/tr[./td[not (@data-empty-grid-message)]]"
+        rows = tableObject.find_elements(By.XPATH, xpath)
+        return len(rows)

robo_appian/controllers/ComponentDriver.py

@@ -12,25 +12,70 @@ from robo_appian.components.SearchDropdownUtils import SearchDropdownUtils
 
 class ComponentDriver:
     """
-    Utility class for interacting with various components in Appian UI.
-    Usage Example:
-    from robo_appian.utils.controllers.ComponentDriver import ComponentDriver
-    # Set a date value
-    ComponentDriver.execute(wait, "Date", "Set Value", "Start Date", "01/01/2024")
+    High-level action router for Appian UI components: unifies all component interactions.
+
+    Instead of importing individual utilities (InputUtils, ButtonUtils, etc.), use ComponentDriver
+    to route actions by component type and label. This simplifies test code and centralizes
+    the mapping between component types and available actions.
+
+    Supported component types: Date, Input Text, Button, Drop Down, Search Input Text,
+    Search Drop Down, Label, Link, Tab.
+
+    All methods follow the wait-first pattern: pass WebDriverWait as the first argument.
+
+    Examples:
+        >>> from robo_appian.controllers.ComponentDriver import ComponentDriver
+        >>> # Set a date value
+        >>> ComponentDriver.execute(wait, "Date", "Set Value", "Start Date", "01/01/2024")
+        >>> # Fill a text input
+        >>> ComponentDriver.execute(wait, "Input Text", "Set Value", "Username", "john_doe")
+        >>> # Click a button
+        >>> ComponentDriver.execute(wait, "Button", "Click", "Submit", None)
+        >>> # Select dropdown option
+        >>> ComponentDriver.execute(wait, "Drop Down", "Select", "Status", "Active")
     """
 
     @staticmethod
     def execute(wait: WebDriverWait, type, action, label, value):
         """
-        Executes an action on a specified component type.
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            type: The type of component (e.g., "Date", "Input Text", "Search Input Text", etc.).
-            action: The action to perform on the component (e.g., "Set Value", "Click", "Select").
-            label: The visible text label of the component.
-            value: The value to set in the component (if applicable).
-        Example:
-            ComponentDriver.execute(wait, "Date", "Set Value", "Start Date", "01/01/2024")
+        Execute a high-level action on an Appian component by type, action, label, and value.
+
+        Routes the action to the appropriate utility class (InputUtils, ButtonUtils, etc.) based
+        on component type and action. Eliminates need for direct utility imports in tests.
+
+        Args:
+            wait: WebDriverWait instance (required by all robo_appian utilities).
+            type: Component type string. Supported: "Date", "Input Text", "Button", "Drop Down",
+                "Search Input Text", "Search Drop Down", "Label", "Link", "Tab".
+            action: Action string. Common values: "Set Value", "Click", "Select", "Find".
+                Valid actions depend on component type (see supported combinations below).
+            label: Exact visible label text of the component on the page (used to locate element).
+            value: Value to set or select. None for click/find actions; required for Set Value/Select.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If component type or action is not supported.
+            TimeoutException: If component not found or not clickable within wait timeout.
+
+        Examples:
+            >>> # Set date value
+            >>> ComponentDriver.execute(wait, "Date", "Set Value", "Start Date", "01/01/2024")
+            >>> # Fill text input
+            >>> ComponentDriver.execute(wait, "Input Text", "Set Value", "Email", "test@example.com")
+            >>> # Click button
+            >>> ComponentDriver.execute(wait, "Button", "Click", "Submit", None)
+            >>> # Select dropdown
+            >>> ComponentDriver.execute(wait, "Drop Down", "Select", "Department", "Sales")
+            >>> # Search and select from search dropdown
+            >>> ComponentDriver.execute(wait, "Search Drop Down", "Select", "Employee", "John Doe")
+            >>> # Click link
+            >>> ComponentDriver.execute(wait, "Link", "Click", "Learn More", None)
+            >>> # Check if label exists
+            >>> ComponentDriver.execute(wait, "Label", "Find", "Important Notice", None)
+            >>> # Select tab
+            >>> ComponentDriver.execute(wait, "Tab", "Find", "Details", None)
         """
         # This method executes an action on a specified component type based on the provided parameters.
 
@@ -50,7 +95,9 @@ class ComponentDriver:
             case "Search Input Text":
                 match action:
                     case "Select":
-                        SearchInputUtils.selectSearchDropdownByLabelText(wait, label, value)
+                        SearchInputUtils.selectSearchDropdownByLabelText(
+                            wait, label, value
+                        )
                     case _:
                         raise ValueError(f"Unsupported action for {type}: {action}")
             case "Label":
@@ -74,7 +121,9 @@ class ComponentDriver:
             case "Search Drop Down":
                 match action:
                     case "Select":
-                        SearchDropdownUtils.selectSearchDropdownValueByLabelText(wait, label, value)
+                        SearchDropdownUtils.selectSearchDropdownValueByLabelText(
+                            wait, label, value
+                        )
                     case _:
                         raise ValueError(f"Unsupported action for {type}: {action}")
             case "Button":

robo_appian/exceptions/MyCustomError.py

@@ -1,5 +1,17 @@
 class MyCustomError(Exception):
-    """A custom exception for specific error conditions."""
+    """
+    Custom exception for robo_appian-specific error conditions.
+
+    Use this exception when robo_appian operations encounter conditions that require
+    special handling distinct from standard Selenium or Python exceptions.
+
+    Examples:
+        >>> raise MyCustomError("Element not found in expected state")
+        >>> try:
+        ...     some_operation()
+        ... except MyCustomError as e:
+        ...     print(f"Custom error occurred: {e.message}")
+    """
 
     def __init__(self, message="This is a custom error!"):
         self.message = message