pyxecm 1.3.0__py3-none-any.whl → 1.5__py3-none-any.whl

pyxecm/customizer/__init__.py

@@ -1,6 +1,12 @@
 """PYXECM classes for Customizer"""
+
+from .browser_automation import BrowserAutomation
+
 from .customizer import Customizer
 from .k8s import K8s
 from .m365 import M365
 from .payload import Payload
 from .sap import SAP
+from .salesforce import Salesforce
+from .successfactors import SuccessFactors
+from .servicenow import ServiceNow

pyxecm/customizer/browser_automation.py

@@ -6,10 +6,17 @@ no REST API or LLConfig can be used.
 Class: BrowserAutomation
 Methods:
 
-__init__ : class initializer
+__init__ : class initializer. Start the browser session.
 set_chrome_options: Sets chrome options for Selenium. Chrome options for headless browser is enabled
-run_otcs_login: Login to OTCS via the browser
-run_configure_vertex_datasource: Run the configuration of the Aviator Vertex datasource
+get_page: Load a page into the browser based on a given URL.
+find_elem: Find an page element
+find_elem_and_click: Find an page element and click it
+find_elem_and_set: Find an page element and fill it with a new text.
+find_element_and_download: Clicks a page element to initiate a download.
+run_login: Login to target system via the browser
+implicit_wait: Waits for the browser to finish tasks (e.g. fully loading a page).
+               This setting is valid for the whole browser session.
+               See https://www.selenium.dev/documentation/webdriver/waits/
 end_session: End the browser session
 """
 
@@ -25,12 +32,17 @@ try:
     from selenium.webdriver.chrome.options import Options
     from selenium import webdriver
     from selenium.webdriver.common.by import By
+    from selenium.webdriver.common.action_chains import ActionChains
+    from selenium.webdriver.remote.webelement import WebElement
     from selenium.common.exceptions import (
         WebDriverException,
         NoSuchElementException,
         ElementNotInteractableException,
         ElementClickInterceptedException,
+        TimeoutException,
+        MoveTargetOutOfBoundsException,
     )
+
 except ModuleNotFoundError as module_exception:
     logger.warning("Module selenium is not installed")
 
@@ -42,11 +54,14 @@ except ModuleNotFoundError as module_exception:
 
         ID: str = ""
 
+    class WebElement:
+        """Dummy class to avoid errors if selenium module cannot be imported"""
+
 
 try:
     import chromedriver_autoinstaller
 except ModuleNotFoundError as module_exception:
-    logger.warning("Module chromedriver_autoinstaller is not installed")
+    logger.warning("Module chromedriver_autoinstaller is not installed!")
 
 
 class BrowserAutomation:
@@ -54,10 +69,12 @@ class BrowserAutomation:
 
     def __init__(
         self,
-        base_url: str,
-        user_name: str,
-        user_password: str,
+        base_url: str = "",
+        user_name: str = "",
+        user_password: str = "",
         download_directory: str = "/tmp",
+        take_screenshots: bool = False,
+        automation_name: str = "screen",
     ) -> None:
         self.base_url = base_url
         self.user_name = user_name
@@ -65,6 +82,16 @@ class BrowserAutomation:
         self.logged_in = False
         self.download_directory = download_directory
 
+        self.take_screenshots = take_screenshots
+        self.screenshot_names = automation_name
+        self.screen_counter = 1
+
+        self.screenshot_directory = "/tmp/browser_automations/{}".format(
+            automation_name
+        )
+
+        if self.take_screenshots and not os.path.exists(self.screenshot_directory):
+            os.makedirs(self.screenshot_directory)
         chromedriver_autoinstaller.install()
         self.browser = webdriver.Chrome(options=self.set_chrome_options())
 
@@ -100,9 +127,24 @@ class BrowserAutomation:
 
     # end method definition
 
+    def take_screenshot(self) -> bool:
+        """Take a screenshot of the current browser window and save it as PNG file
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+
+        screenshot_file = "{}/{}-{}.png".format(
+            self.screenshot_directory, self.screenshot_names, self.screen_counter
+        )
+        logger.debug("Save browser screenshot to -> %s", screenshot_file)
+        result = self.browser.get_screenshot_as_file(screenshot_file)
+        self.screen_counter += 1
+
+        return result
+
     def get_page(self, url: str = "") -> bool:
         """Load a page into the browser based on a given URL.
-           Required authorization need
 
         Args:
             url (str): URL to load. If empty just the base URL will be used
@@ -113,26 +155,77 @@ class BrowserAutomation:
         page_url = self.base_url + url
 
         try:
-            logger.info("Load page -> %s", page_url)
+            logger.debug("Load page -> %s", page_url)
             self.browser.get(page_url)
         except WebDriverException as exception:
             logger.error("Cannot load page -> %s; error -> %s", page_url, exception)
             return False
 
-        logger.info("Page title after get page -> %s", self.browser.title)
+        logger.debug("Page title after get page -> %s", self.browser.title)
+
+        if self.take_screenshots:
+            self.take_screenshot()
 
         return True
 
     # end method definition
 
-    def find_elem_and_click(self, find_elem: str, find_method: str = By.ID) -> bool:
-        """Find an page element and click it.
+    def get_title(self) -> str:
+        """Get the browser title. This is handy to validate a certain page is loaded after get_page()
+
+        Returns:
+            str: Title of the browser window
+        """
+
+        if not self.browser:
+            logger.error("Browser not initialized!")
+            return None
+
+        return self.browser.title
+
+    # end method definition
+
+    def scroll_to_element(self, element: WebElement):
+        """Scroll an element into view to make it clickable
+
+        Args:
+            element (WebElement): Web element that has been identified before
+        """
+
+        if not element:
+            logger.error("Undefined element!")
+            return
+
+        try:
+            actions = ActionChains(self.browser)
+            actions.move_to_element(element).perform()
+        except NoSuchElementException:
+            logger.error("Element not found in the DOM")
+        except TimeoutException:
+            logger.error("Timed out waiting for the element to be present or visible")
+        except ElementNotInteractableException:
+            logger.error("Element is not interactable!")
+        except MoveTargetOutOfBoundsException:
+            logger.error("Element is out of bounds!")
+        except WebDriverException as e:
+            logger.error("WebDriverException occurred -> %s", str(e))
+
+    # end method definition
+
+    def find_elem(
+        self,
+        find_elem: str,
+        find_method: str = By.ID,
+        show_error: bool = True,
+    ) -> WebElement:
+        """Find an page element.
 
         Args:
             find_elem (str): name of the page element
-            find_method (str): either By.ID, By.NAME, By.CLASS_NAME, BY.XPATH
+            find_method (str, optional): either By.ID, By.NAME, By.CLASS_NAME, BY.XPATH
+            show_error (bool, optional): show an error if the element is not found or not clickable
         Returns:
-            bool: True if successful, False otherwise
+            WebElement: web element or None in case an error occured.
         """
 
         # We don't want to expose class "By" outside this module,
@@ -147,72 +240,136 @@ class BrowserAutomation:
             find_method = By.XPATH
         else:
             logger.error("Unsupported find method!")
-            return False
+            return None
 
         try:
             elem = self.browser.find_element(by=find_method, value=find_elem)
         except NoSuchElementException as exception:
+            if show_error:
+                logger.error(
+                    "Cannot find page element -> %s by -> %s; error -> %s",
+                    find_elem,
+                    find_method,
+                    exception,
+                )
+                return None
+            else:
+                logger.warning(
+                    "Cannot find page element -> %s by -> %s",
+                    find_elem,
+                    find_method,
+                )
+                return None
+        except TimeoutException as exception:
             logger.error(
-                "Cannot find page element -> %s by -> %s; error -> %s",
-                find_elem,
-                find_method,
+                "Timed out waiting for the element to be present or visible; error -> %s",
                 exception,
             )
+            return None
+        except ElementNotInteractableException as exception:
+            logger.error("Element is not interactable!; error -> %s", exception)
+            return None
+        except MoveTargetOutOfBoundsException:
+            logger.error("Element is out of bounds!")
+            return None
+        except WebDriverException as e:
+            logger.error("WebDriverException occurred -> %s", str(e))
+            return None
+
+        logger.debug("Found page element -> %s by -> %s", find_elem, find_method)
+
+        return elem
+
+    # end method definition
+
+    def find_elem_and_click(
+        self,
+        find_elem: str,
+        find_method: str = By.ID,
+        scroll_to_element: bool = True,
+        show_error: bool = True,
+    ) -> bool:
+        """Find an page element and click it.
+
+        Args:
+            find_elem (str): name of the page element
+            find_method (str, optional): either By.ID, By.NAME, By.CLASS_NAME, BY.XPATH
+            scroll_to_element (bool, optional): scroll the element into view
+            show_error (bool, optional): show an error if the element is not found or not clickable
+        Returns:
+            bool: True if successful, False otherwise
+        """
+
+        if not find_elem:
+            if show_error:
+                logger.error("Missing element name! Cannot find HTML element!")
+            else:
+                logger.warning("Missing element name! Cannot find HTML element!")
             return False
 
+        elem = self.find_elem(
+            find_elem=find_elem, find_method=find_method, show_error=show_error
+        )
+
+        if not elem:
+            return not show_error
+
         try:
+            if scroll_to_element:
+                self.scroll_to_element(elem)
+
             elem.click()
-        except ElementClickInterceptedException as exception:
-            logger.error(
-                "Cannot click page element -> %s; error -> %s", find_elem, exception
-            )
-            return False
+        except (
+            ElementClickInterceptedException,
+            ElementNotInteractableException,
+        ) as exception:
+            if show_error:
+                logger.error(
+                    "Cannot click page element -> %s; error -> %s", find_elem, exception
+                )
+                return False
+            else:
+                logger.warning("Cannot click page element -> %s", find_elem)
+                return True
+
+        logger.debug("Successfully clicked element -> %s", find_elem)
+
+        if self.take_screenshots:
+            self.take_screenshot()
 
         return True
 
     # end method definition
 
     def find_elem_and_set(
-        self, find_elem: str, elem_value: str, find_method: str = By.ID
+        self,
+        find_elem: str,
+        elem_value: str,
+        find_method: str = By.ID,
+        is_sensitive: bool = False,
     ) -> bool:
         """Find an page element and fill it with a new text.
 
         Args:
             find_elem (str): name of the page element
             elem_value (str): new text string for the page element
-            find_method (str): either By.ID, By.NAME, By.CLASS_NAME, or By.XPATH
+            find_method (str, optional): either By.ID, By.NAME, By.CLASS_NAME, or By.XPATH
+            is_sensitive (bool, optional): True for suppressing sensitive information in logging
         Returns:
             bool: True if successful, False otherwise
         """
 
-        # We don't want to expose class "By" outside this module,
-        # so we map the string values to the By class values:
-        if find_method == "id":
-            find_method = By.ID
-        elif find_method == "name":
-            find_method = By.NAME
-        elif find_method == "class_name":
-            find_method = By.CLASS_NAME
-        elif find_method == "xpath":
-            find_method = By.XPATH
-        else:
-            logger.error("Unsupported find method!")
-            return False
-
-        logger.info("Try to find element -> %s by -> %s...", find_elem, find_method)
+        elem = self.find_elem(
+            find_elem=find_elem, find_method=find_method, show_error=True
+        )
 
-        try:
-            elem = self.browser.find_element(find_method, find_elem)
-        except NoSuchElementException as exception:
-            logger.error(
-                "Cannot find page element -> %s by -> %s; error -> %s",
-                find_elem,
-                find_method,
-                exception,
-            )
+        if not elem:
             return False
 
-        logger.info("Set element -> %s to value -> %s...", find_elem, elem_value)
+        if not is_sensitive:
+            logger.debug("Set element -> %s to value -> %s...", find_elem, elem_value)
+        else:
+            logger.debug("Set element -> %s to value -> <sensitive>...", find_elem)
 
         try:
             elem.clear()  # clear existing text in the input field
@@ -272,30 +429,46 @@ class BrowserAutomation:
         user_field: str = "otds_username",
         password_field: str = "otds_password",
         login_button: str = "loginbutton",
+        page: str = "",
     ) -> bool:
         """Login to target system via the browser"""
 
         self.logged_in = False
 
         if (
-            not self.get_page()  # assuming the base URL leads towards the login page
+            not self.get_page(
+                url=page
+            )  # assuming the base URL leads towards the login page
             or not self.find_elem_and_set(
                 find_elem=user_field, elem_value=self.user_name
             )
             or not self.find_elem_and_set(
-                find_elem=password_field, elem_value=self.user_password
+                find_elem=password_field,
+                elem_value=self.user_password,
+                is_sensitive=True,
             )
             or not self.find_elem_and_click(find_elem=login_button)
         ):
-            logger.error("Cannot log into target system using URL -> %s", self.base_url)
+            logger.error(
+                "Cannot log into target system using URL -> %s and user -> %s",
+                self.base_url,
+                self.user_name,
+            )
             return False
 
-        logger.info("Page title after login -> %s", self.browser.title)
+        logger.debug("Page title after login -> %s", self.browser.title)
+
+        # Some special handling for Salesforce login:
         if "Verify" in self.browser.title:
             logger.error(
                 "Site is asking for a Verification Token. You may need to whitelist your IP!"
             )
             return False
+        if "Login" in self.browser.title:
+            logger.error(
+                "Authentication failed. You may have given the wrong password!"
+            )
+            return False
 
         self.logged_in = True
 
@@ -303,14 +476,16 @@ class BrowserAutomation:
 
     # end method definition
 
-    def implict_wait(self, wait_time: float):
+    def implicit_wait(self, wait_time: float):
         """Waits for the browser to finish tasks (e.g. fully loading a page)
+           This setting is valid for the whole browser session and not just
+           for a single command.
 
         Args:
             wait_time (float): time in seconds to wait
         """
 
-        logger.info("Implicit wait for max -> %s seconds...", str(wait_time))
+        logger.debug("Implicit wait for max -> %s seconds...", str(wait_time))
         self.browser.implicitly_wait(wait_time)
 
     def end_session(self):