robo_appian 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

robo_appian/components/ButtonUtils.py

@@ -4,8 +4,30 @@ from selenium.webdriver.support.ui import WebDriverWait
 
 
 class ButtonUtils:
+    """
+    Utility class for interacting with button components in Appian UI.
+    Usage Example:
+        # Click a button by its label
+        from robo_appian.components.ButtonUtils import ButtonUtils
+        ButtonUtils.clickByLabelText(wait, "Submit")
+    """
+
     @staticmethod
-    def find(wait: WebDriverWait, label: str):
+    def __findByPartialLabelText(wait: WebDriverWait, label: str):
+        """
+        Finds a button by its label.
+
+        Parameters:
+            wait: Selenium WebDriverWait instance.
+            label: The label of the button to find.
+            label: The label of the button to find.
+
+        Returns:
+            WebElement representing the button.
+
+        Example:
+            component = ButtonUtils.__findByLabelText(wait, "Submit")
+        """
         xpath = f".//button[./span[contains(translate(normalize-space(.), '\u00a0', ' '), '{label}')]]"
         try:
             component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
@@ -14,22 +36,56 @@ class ButtonUtils:
         return component
 
     @staticmethod
-    def click(wait: WebDriverWait, label: str):
+    def __findByLabelText(wait: WebDriverWait, label: str):
         """
-        Clicks a button identified by its label.
+        Finds a button by its label.
 
         Parameters:
             wait: Selenium WebDriverWait instance.
-            label: The visible text label of the button.
+            label: The label of the button to find.
+            label: The label of the button to find.
+
+        Returns:
+            WebElement representing the button.
+
         Example:
-            ButtonUtils.click(wait, "Submit")
+            component = ButtonUtils.__findByLabelText(wait, "Submit")
+        """
+        xpath = f".//button[./span[normalize-space(text())='{label}']]"
+        try:
+            component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
+        except Exception as e:
+            raise RuntimeError(f"Button with label '{label}' not found or not clickable.") from e
+        return component
+
+    @staticmethod
+    def clickByPartialLabelText(wait: WebDriverWait, label: str):
+        """Finds a button by its partial label and clicks it.
+
+        Parameters:
+            wait: Selenium WebDriverWait instance.
+            label: The partial label of the button to click.
+            Example:
+                ButtonUtils.clickByPartialLabelText(wait, "Button Label")
+        """
+        component = ButtonUtils.__findByPartialLabelText(wait, label)
+        component.click()
 
+    @staticmethod
+    def clickByLabelText(wait: WebDriverWait, label: str):
+        """Finds a button by its label and clicks it.
+
+        Parameters:
+            wait: Selenium WebDriverWait instance.
+            label: The label of the button to click.
+            Example:
+                ButtonUtils.clickByLabelText(wait, "Button Label")
         """
-        component = ButtonUtils.find(wait, label)
+        component = ButtonUtils.__findByLabelText(wait, label)
         component.click()
 
     @staticmethod
-    def clickInputButtonById(wait: WebDriverWait, id: str):
+    def clickById(wait: WebDriverWait, id: str):
         """
         Finds and clicks an input button by its HTML id attribute.
 
@@ -38,13 +94,11 @@ class ButtonUtils:
             id: The HTML id of the input button.
 
         Example:
-            ButtonUtils.clickInputButtonById(wait, "button_id")
+            ButtonUtils.clickById(wait, "button_id")
 
         """
         try:
             component = wait.until(EC.element_to_be_clickable((By.ID, id)))
-        except TimeoutError as e:
-            raise TimeoutError(f"Input button with id '{id}' not found or not clickable.") from e
         except Exception as e:
             raise RuntimeError(f"Input button with id '{id}' not found or not clickable.") from e
 

robo_appian/components/DateUtils.py

@@ -1,7 +1,6 @@
 from selenium.webdriver.common.by import By
 from selenium.webdriver.support import expected_conditions as EC
 from selenium.webdriver.support.ui import WebDriverWait
-from selenium.webdriver.remote.webelement import WebElement
 
 from robo_appian.components.InputUtils import InputUtils
 
@@ -9,137 +8,70 @@ from robo_appian.components.InputUtils import InputUtils
 class DateUtils:
     """
     Utility class for interacting with date components in Appian UI.
-
-        Usage Example:
-
-        # Set a date value
+    Usage Example:
+        # Set a date value in a date component
         from robo_appian.components.DateUtils import DateUtils
-        DateUtils.setDateValue(wait, "Start Date", "01/01/2024")
-
+        DateUtils.setValueByLabelText(wait, "Start Date", "2023-10-01")
     """
 
     @staticmethod
-    def findComponent(wait: WebDriverWait, label: str):
+    def __findComponent(wait: WebDriverWait, label: str):
         """
         Finds a date component by its label.
-
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the date component.
-
-        Returns:
-            The Selenium WebElement for the date component.
-
+        :param wait: WebDriverWait instance to wait for elements.
+        :param label: The label of the date component.
+        :return: The WebElement representing the date component.
         Example:
-            DateUtils.findComponent(wait, "Start Date")
-
+            DateUtils.__findComponent(wait, "Start Date")
         """
-
-        xpath = f".//div/label[text()='{label}']"
-        try:
-            component: WebElement = wait.until(
-                EC.element_to_be_clickable((By.XPATH, xpath))
-            )
-        except TimeoutError as e:
-            raise TimeoutError(
-                f"Could not find clickable date component with label '{label}': {e}"
-            )
-        except Exception as e:
-            raise Exception(
-                f"Could not find clickable date component with label '{label}': {e}"
-            )
-
-        attribute: str = "for"
-        component_id = component.get_attribute(attribute)  # type: ignore[reportUnknownMemberType]
-        if component_id is None:
-            raise ValueError(
-                f"Could not find component using {attribute} attribute for label '{label}'."
-            )
-
+        # xpath = f".//div/label[text()='{label}']"
+        # try:
+        #     component: WebElement = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
+        # except Exception as e:
+        #     raise Exception(f"Could not find clickable date component with label '{label}': {e}")
+
+        # attribute: str = "for"
+        # component_id = component.get_attribute(attribute)  # type: ignore[reportUnknownMemberType]
+        # if component_id is None:
+        #     raise ValueError(f"Could not find component using {attribute} attribute for label '{label}'.")
+
+        # try:
+        #     component = wait.until(EC.element_to_be_clickable((By.ID, component_id)))
+        # except Exception as e:
+        #     raise Exception(f"Could not find clickable date input with id '{component_id}': {e}")
+
+        xpath = f'.//div[./div/label[text()="{label}"]]/div/div/div/input'
         try:
-            component = wait.until(EC.element_to_be_clickable((By.ID, component_id)))
-        except TimeoutError as e:
-            raise TimeoutError(
-                f"Could not find clickable date input with id '{component_id}': {e}"
-            )
+            component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
         except Exception as e:
-            raise Exception(
-                f"Could not find clickable date input with id '{component_id}': {e}"
-            )
+            raise Exception(f"Could not find clickable date component with label '{label}': {e}")
         return component
 
     @staticmethod
-    def setDateValue(wait: WebDriverWait, label: str, value: str):
+    def setValueByLabelText(wait: WebDriverWait, label: str, value: str):
         """
-        Sets a date value in a date component identified by its label.
-
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the date component.
-            value: The date value to set (e.g., "01/01/2024").
-
-        Returns:
-            The Selenium WebElement for the date component after setting the value.
-
+        Sets the value of a date component.
+        :param wait: WebDriverWait instance to wait for elements.
+        :param label: The label of the date component.
+        :param value: The value to set in the date component.
+        :return: The WebElement representing the date component.
         Example:
-            DateUtils.setDateValue(wait, "Start Date", "01/01/2024")
-
+            DateUtils.setValueByLabelText(wait, "Start Date", "2023-10-01")
         """
-        # This method locates a date component that contains a label with the specified text.
-        # It then retrieves the component's ID and uses it to find the actual input element.
-        # component = wait.until(EC.element_to_be_clickable((By.XPATH, f".//div/label[text()='{label}']/following-sibling::input")))
-
-        component = DateUtils.findComponent(wait, label)
-        InputUtils._setComponentValue(component, value)
+        component = DateUtils.__findComponent(wait, label)
+        InputUtils._setValueByComponent(component, value)
         return component
 
     @staticmethod
-    def setDateValueAndSubmit(wait: WebDriverWait, label: str, value: str):
+    def clickByLabelText(wait: WebDriverWait, label: str):
         """
-        Sets a date value in a date component identified by its label and submits the form.
-
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the date component.
-            value: The date value to set (e.g., "01/01/2024").
-
-        Returns:
-            The Selenium WebElement for the date component after setting the value.
-
+        Clicks on the date component to open the date picker.
+        :param wait: WebDriverWait instance to wait for elements.
+        :param label: The label of the date component.
+        :return: The WebElement representing the date component.
         Example:
-            DateUtils.setDateValueAndSubmit(wait, "Start Date", "01/01/2024")
-
+            DateUtils.clickByLabelText(wait, "Start Date")
         """
-
-        # This method locates a date component that contains a label with the specified text.
-        # It then retrieves the component's ID and uses it to find the actual input element.
-        # It sets the value of the input element and submits it.
-
-        component = DateUtils.findComponent(wait, label)
-        InputUtils.setValueAndSubmitByComponent(component, value)
-
-        return component
-
-    @staticmethod
-    def click(wait: WebDriverWait, label: str):
-        """
-        Clicks on a date component identified by its label.
-
-        Parameters:
-            wait: Selenium WebDriverWait instance.
-            label: The visible text label of the date component.
-
-        Returns:
-            The Selenium WebElement for the date component after clicking.
-
-        Example:
-            DateUtils.click(wait, "Start Date")
-        """
-        # This method locates a date component that contains a label with the specified text.
-        # It then retrieves the component's ID and uses it to find the actual input element.
-        # It clicks on the input element to open the date picker.
-
-        component = DateUtils.findComponent(wait, label)
+        component = DateUtils.__findComponent(wait, label)
         component.click()
-
         return component

robo_appian/components/DropdownUtils.py

@@ -16,7 +16,16 @@ class DropdownUtils:
 
     @staticmethod
     def __findComboboxByPartialLabelText(wait: WebDriverWait, label: str):
-        xpath = f'.//div[./div/span[contains(normalize-space(text()), "{label}")]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'
+        """
+        Finds a combobox by its partial label text.
+
+        :param wait: Selenium WebDriverWait instance.
+        :param label: The partial label of the combobox to find.
+        :return: WebElement representing the combobox.
+        Example:
+            component = DropdownUtils.__findComboboxByPartialLabelText(wait, "Dropdown Label")
+        """
+        xpath = f'.//div[./div/span[contains(normalize-space(text()), "{label}")]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'  # noqa: E501
         try:
             component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
         except Exception as e:
@@ -26,7 +35,16 @@ class DropdownUtils:
 
     @staticmethod
     def __findComboboxByLabelText(wait: WebDriverWait, label: str):
-        xpath = f'.//div[./div/span[normalize-space(text())="{label}"]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'
+        """
+        Finds a combobox by its label text.
+
+        :param wait: Selenium WebDriverWait instance.
+        :param label: The label of the combobox to find.
+        :return: WebElement representing the combobox.
+        Example:
+            component = DropdownUtils.__findComboboxByLabelText(wait, "Dropdown Label")
+        """
+        xpath = f'.//div[./div/span[normalize-space(text())="{label}"]]/div/div/div/div[@role="combobox" and not(@aria-disabled="true")]'  # noqa: E501
         try:
             component = wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
         except Exception as e:
@@ -36,10 +54,27 @@ class DropdownUtils:
 
     @staticmethod
     def __clickCombobox(wait: WebDriverWait, combobox: WebElement):
+        """
+        Clicks the combobox to open the dropdown options.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param combobox: The combobox WebElement.
+        Example:
+            DropdownUtils.__clickCombobox(wait, combobox)
+        """
         combobox.click()
 
     @staticmethod
     def __findDropdownOptionId(wait: WebDriverWait, combobox: WebElement):
+        """
+        Finds the dropdown option id from the combobox.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param combobox: The combobox WebElement.
+        :return: The id of the dropdown options list.
+        Example:
+            dropdown_option_id = DropdownUtils.__findDropdownOptionId(wait, combobox)
+        """
         dropdown_option_id = combobox.get_attribute("aria-controls")
         if dropdown_option_id is None:
             raise Exception('Dropdown component does not have a valid "aria-controls" attribute.')
@@ -47,9 +82,23 @@ class DropdownUtils:
 
     @staticmethod
     def __checkDropdownOptionValueExistsByDropdownOptionId(wait: WebDriverWait, dropdown_option_id: str, value: str):
-        option_xpath = f'.//div/ul[@id="{dropdown_option_id}"]/li[./div[normalize-space(text())="{value}"]]'
+        """
+        Checks if a dropdown option value exists by its option id and value.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param dropdown_option_id: The id of the dropdown options list.
+        :param value: The value to check in the dropdown.
+        Example:
+            exists = DropdownUtils.checkDropdownOptionValueExistsByDropdownOptionId(wait, "dropdown_option_id", "Option Value")
+            if exists:
+                print("The value exists in the dropdown.")
+            else:
+                print("The value does not exist in the dropdown.")
+        """
+
+        xpath = f'.//div/ul[@id="{dropdown_option_id}"]/li[./div[normalize-space(text())="{value}"]]'
         try:
-            wait.until(EC.element_to_be_clickable((By.XPATH, option_xpath)))
+            wait.until(EC.element_to_be_clickable((By.XPATH, xpath)))
             return True
         except NoSuchElementException:
             return False
@@ -58,6 +107,15 @@ class DropdownUtils:
 
     @staticmethod
     def __selectDropdownValueByDropdownOptionId(wait: WebDriverWait, dropdown_option_id: str, value: str):
+        """
+        Selects a value from a dropdown by its option id and value.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param dropdown_option_id: The id of the dropdown options list.
+        :param value: The value to select from the dropdown.
+        Example:
+            DropdownUtils.selectDropdownValueByDropdownOptionId(wait, "dropdown_option_id", "Option Value")
+        """
         option_xpath = f'.//div/ul[@id="{dropdown_option_id}"]/li[./div[normalize-space(text())="{value}"]]'
         try:
             try:
@@ -65,7 +123,7 @@ class DropdownUtils:
                 component = wait.until(EC.element_to_be_clickable((By.XPATH, option_xpath)))
             except Exception as e:
                 raise Exception(
-                    f'Could not locate or click dropdown option "{value}" with dropdown option id "{dropdown_option_id}": {str(e)}'
+                    f'Could not locate or click dropdown option "{value}" with dropdown option id "{dropdown_option_id}": {str(e)}'  # noqa: E501
                 )
         except Exception as e:
             raise Exception(f'Could not find or click dropdown option "{value}" with xpath "{option_xpath}": {str(e)}')
@@ -101,6 +159,19 @@ class DropdownUtils:
 
     @staticmethod
     def checkReadOnlyStatusByLabelText(wait: WebDriverWait, label: str):
+        """
+        Checks if a dropdown is read-only by its label text.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param label: The label of the dropdown.
+        :return: True if the dropdown is read-only, False otherwise.
+        Example:
+            is_read_only = DropdownUtils.checkReadOnlyStatusByLabelText(wait, "Dropdown Label")
+            if is_read_only:
+                print("The dropdown is read-only.")
+            else:
+                print("The dropdown is editable.")
+        """
         xpath = f'.//div[./div/span[normalize-space(text())="{label}"]]/div/div/p[text()]'
         try:
             wait._driver.find_element(By.XPATH, xpath)
@@ -112,20 +183,61 @@ class DropdownUtils:
 
     @staticmethod
     def selectDropdownValueByComboboxComponent(wait: WebDriverWait, combobox: WebElement, value: str):
+        """
+        Selects a value from a dropdown using the combobox component.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param combobox: The combobox WebElement.
+        :param value: The value to select from the dropdown.
+        Example:
+            DropdownUtils.selectDropdownValueByComboboxComponent(wait, combobox, "Option Value")
+        """
         dropdown_option_id = DropdownUtils.__findDropdownOptionId(wait, combobox)
         DropdownUtils.__clickCombobox(wait, combobox)
         DropdownUtils.__selectDropdownValueByDropdownOptionId(wait, dropdown_option_id, value)
 
     @staticmethod
     def selectDropdownValueByLabelText(wait: WebDriverWait, dropdown_label: str, value: str):
+        """
+        Selects a value from a dropdown by its label text.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param dropdown_label: The label of the dropdown.
+        :param value: The value to select from the dropdown.
+        Example:
+            DropdownUtils.selectDropdownValueByLabelText(wait, "Dropdown Label", "Option Value")
+        """
         DropdownUtils.__selectDropdownValueByLabelText(wait, dropdown_label, value)
 
     @staticmethod
     def selectDropdownValueByPartialLabelText(wait: WebDriverWait, dropdown_label: str, value: str):
+        """
+        Selects a value from a dropdown by its partial label text.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param dropdown_label: The partial label of the dropdown.
+        :param value: The value to select from the dropdown.
+        Example:
+            DropdownUtils.selectDropdownValueByPartialLabelText(wait, "Dropdown Label", "Option Value")
+        """
         DropdownUtils.__selectDropdownValueByPartialLabelText(wait, dropdown_label, value)
 
     @staticmethod
     def checkDropdownOptionValueExists(wait: WebDriverWait, dropdown_label: str, value: str):
+        """
+        Checks if a dropdown option value exists by its label text.
+
+        :param wait: WebDriverWait instance to wait for elements.
+        :param dropdown_label: The label of the dropdown.
+        :param value: The value to check in the dropdown.
+        :return: True if the value exists, False otherwise.
+        Example:
+            exists = DropdownUtils.checkDropdownOptionValueExists(wait, "Dropdown Label", "Option Value")
+            if exists:
+                print("The value exists in the dropdown.")
+            else:
+                print("The value does not exist in the dropdown.")
+        """
         combobox = DropdownUtils.__findComboboxByLabelText(wait, dropdown_label)
         DropdownUtils.__clickCombobox(wait, combobox)
         dropdown_option_id = DropdownUtils.__findDropdownOptionId(wait, combobox)