pyxecm 3.0.1__py3-none-any.whl → 3.1.1__py3-none-any.whl

pyxecm_customizer/browser_automation.py

@@ -90,14 +90,20 @@ except ModuleNotFoundError:
 # "wait until" strategy.
 DEFAULT_WAIT_UNTIL_STRATEGY = "networkidle"
 
-REQUEST_TIMEOUT = 30
-REQUEST_RETRY_DELAY = 2
+REQUEST_TIMEOUT = 30.0
+REQUEST_RETRY_DELAY = 2.0
 REQUEST_MAX_RETRIES = 3
 
 
 class BrowserAutomation:
     """Class to automate settings via a browser interface."""
 
+    page: Page = None
+    browser: Browser = None
+    context: BrowserContext = None
+    playwright = None
+    proxy = None
+
     logger: logging.Logger = default_logger
 
     def __init__(
@@ -182,11 +188,10 @@ class BrowserAutomation:
             self.screenshot_names,
             "screenshots",
         )
-        self.logger.debug("Creating Screenshot directory... -> %s", self.screenshot_directory)
+        self.logger.debug("Creating screenshot directory... -> %s", self.screenshot_directory)
         if self.take_screenshots and not os.path.exists(self.screenshot_directory):
             os.makedirs(self.screenshot_directory)
 
-        self.proxy = None
         if os.getenv("HTTP_PROXY"):
             self.proxy = {
                 "server": os.getenv("HTTP_PROXY"),
@@ -194,21 +199,22 @@ class BrowserAutomation:
             self.logger.info("Using HTTP proxy -> %s", os.getenv("HTTP_PROXY"))
 
         browser = browser or os.getenv("BROWSER", "webkit")
-        self.logger.info("Using Browser -> '%s'...", browser)
+        self.logger.info("Using browser -> '%s'...", browser)
 
         if not self.setup_playwright(browser=browser):
-            self.logger.error("Failed to initialize Playwright browser automation!")
-            return
+            msg = "Failed to initialize Playwright browser automation!"
+            self.logger.error(msg)
+            raise RuntimeError(msg)
 
-        self.logger.info("Creating Browser Context...")
+        self.logger.info("Creating browser context...")
         self.context: BrowserContext = self.browser.new_context(
             accept_downloads=True,
         )
 
-        self.logger.info("Creating Page...")
+        self.logger.info("Creating page...")
         self.page: Page = self.context.new_page()
         self.main_page = self.page
-        self.logger.info("Browser Automation initialized.")
+        self.logger.info("Browser automation initialized.")
 
     # end method definition
 
@@ -217,7 +223,12 @@ class BrowserAutomation:
 
         Args:
             browser (str):
-                Name of the browser engine.
+                Name of the browser engine. Supported:
+                * chromium
+                * chrome
+                * msedge
+                * webkit
+                * firefox
 
         Returns:
             bool:
@@ -232,6 +243,9 @@ class BrowserAutomation:
             self.logger.error("Failed to start Playwright!")
             return False
 
+        result = True
+
+        # Install and launch the selected browser in Playwright:
         match browser:
             case "chromium":
                 try:
@@ -239,10 +253,11 @@ class BrowserAutomation:
                         headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
                 except Exception:
-                    self.install_browser(browser=browser)
-                    self.browser: Browser = self.playwright.chromium.launch(
-                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
-                    )
+                    result = self.install_browser(browser=browser)
+                    if result:
+                        self.browser: Browser = self.playwright.chromium.launch(
+                            headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
+                        )
 
             case "chrome":
                 try:
@@ -253,13 +268,14 @@ class BrowserAutomation:
                         proxy=self.proxy,
                     )
                 except Exception:
-                    self.install_browser(browser=browser)
-                    self.browser: Browser = self.playwright.chromium.launch(
-                        channel="chrome",
-                        headless=self.headless,
-                        slow_mo=100 if not self.headless else None,
-                        proxy=self.proxy,
-                    )
+                    result = self.install_browser(browser=browser)
+                    if result:
+                        self.browser: Browser = self.playwright.chromium.launch(
+                            channel="chrome",
+                            headless=self.headless,
+                            slow_mo=100 if not self.headless else None,
+                            proxy=self.proxy,
+                        )
 
             case "msedge":
                 try:
@@ -270,13 +286,14 @@ class BrowserAutomation:
                         proxy=self.proxy,
                     )
                 except Exception:
-                    self.install_browser(browser=browser)
-                    self.browser: Browser = self.playwright.chromium.launch(
-                        channel="msedge",
-                        headless=self.headless,
-                        slow_mo=100 if not self.headless else None,
-                        proxy=self.proxy,
-                    )
+                    result = self.install_browser(browser=browser)
+                    if result:
+                        self.browser: Browser = self.playwright.chromium.launch(
+                            channel="msedge",
+                            headless=self.headless,
+                            slow_mo=100 if not self.headless else None,
+                            proxy=self.proxy,
+                        )
 
             case "webkit":
                 try:
@@ -284,10 +301,11 @@ class BrowserAutomation:
                         headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
                 except Exception:
-                    self.install_browser(browser=browser)
-                    self.browser: Browser = self.playwright.webkit.launch(
-                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
-                    )
+                    result = self.install_browser(browser=browser)
+                    if result:
+                        self.browser: Browser = self.playwright.webkit.launch(
+                            headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
+                        )
 
             case "firefox":
                 try:
@@ -295,16 +313,30 @@ class BrowserAutomation:
                         headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
                 except Exception:
-                    self.install_browser(browser=browser)
-                    self.browser: Browser = self.playwright.firefox.launch(
-                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
-                    )
-        return True
+                    result = self.install_browser(browser=browser)
+                    if result:
+                        self.browser: Browser = self.playwright.firefox.launch(
+                            headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
+                        )
+            case _:
+                self.logger.error("Unknown browser -> '%s'. Cannot install and launch it.", browser)
+                result = False
+
+        return result
 
     # end method definition
 
     def install_browser(self, browser: str) -> bool:
-        """Check if browser is already installed if not install it."""
+        """Install a browser with a provided name in Playwright.
+
+        Args:
+            browser (str):
+                Name of the browser to be installed.
+
+        Returns:
+            bool: True = installation successful, False = installation failed.
+
+        """
 
         self.logger.info("Installing Browser -> '%s'...", browser)
         process = subprocess.Popen(
@@ -314,12 +346,13 @@ class BrowserAutomation:
             shell=False,
         )
         output, error = process.communicate()
-        if process.returncode == 0:
-            self.logger.info("Installation completed successfullly.")
+        if process.returncode == 0:  # 0 = success
+            self.logger.info("Successfuly completed installation of browser -> '%s'.", browser)
             self.logger.debug(output.decode())
         else:
-            self.logger.error("Installation failed with -> %s", error.decode())
+            self.logger.error("Installation of browser -> '%s' failed! Error -> %s", browser, error.decode())
             self.logger.error(output.decode())
+            return False
 
         return True
 
@@ -351,19 +384,21 @@ class BrowserAutomation:
 
     # end method definition
 
-    def take_screenshot(self) -> bool:
+    def take_screenshot(self, suffix: str = "") -> bool:
         """Take a screenshot of the current browser window and save it as PNG file.
 
+        Args:
+            suffix (str, optional):
+                Optional suffix to append to the screenshot filename.
+
         Returns:
             bool:
                 True if successful, False otherwise
 
         """
 
-        screenshot_file = "{}/{}-{:02d}.png".format(
-            self.screenshot_directory,
-            self.screenshot_names,
-            self.screenshot_counter,
+        screenshot_file = "{}/{}-{:02d}{}.png".format(
+            self.screenshot_directory, self.screenshot_names, self.screenshot_counter, suffix
         )
         self.logger.debug("Save browser screenshot to -> %s", screenshot_file)
 
@@ -634,6 +669,7 @@ class BrowserAutomation:
         wait_state: str = "visible",
         exact_match: bool | None = None,
         regex: bool = False,
+        occurrence: int = 1,
         iframe: str | None = None,
         repeat_reload: int | None = None,
         repeat_reload_delay: int = 60,
@@ -653,10 +689,19 @@ class BrowserAutomation:
             wait_state (str, optional):
                 Defines if we wait for attached (element is part of DOM) or
                 if we wait for elem to be visible (attached, displayed, and has non-zero size).
+                Possible values are:
+                * "attached" - the element is present in the DOM.
+                * "detached" - the element is not present in the DOM.
+                * "visible" - the element is visible (attached, displayed, and has non-zero size).
+                * "hidden" - the element is hidden (attached, but not displayed).
+                Default is "visible".
             exact_match (bool | None, optional):
                 If an exact matching is required. Default is None (not set).
             regex (bool, optional):
                 Should the name be interpreted as a regular expression?
+            occurrence (int, optional):
+                If multiple elements match the selector, this defines which one to return.
+                Default is 1 (the first one).
             iframe (str | None):
                 Is the element in an iFrame? Then provide the name of the iframe with this parameter.
             repeat_reload (int | None):
@@ -674,17 +719,22 @@ class BrowserAutomation:
 
         """
 
-        failure_message = "Cannot find page element with selector -> '{}' ({}){}{}".format(
+        failure_message = "Cannot find {} page element with selector -> '{}' ({}){}{}{}{}".format(
+            "occurence #{} of".format(occurrence) if occurrence > 1 else "any",
             selector,
             selector_type,
             " and role type -> '{}'".format(role_type) if role_type else "",
             " in iframe -> '{}'".format(iframe) if iframe else "",
+            ", occurrence -> {}".format(occurrence) if occurrence > 1 else "",
+            ", waiting for state -> '{}'".format(wait_state),
         )
-        success_message = "Found page element with selector -> '{}' ('{}'){}{}".format(
+        success_message = "Found {} page element with selector -> '{}' ('{}'){}{}{}".format(
+            "occurence #{} of".format(occurrence) if occurrence > 1 else "a",
             selector,
             selector_type,
             " and role type -> '{}'".format(role_type) if role_type else "",
             " in iframe -> '{}'".format(iframe) if iframe else "",
+            ", occurrence -> {}".format(occurrence) if occurrence > 1 else "",
         )
 
         def do_find() -> Locator | None:
@@ -709,8 +759,13 @@ class BrowserAutomation:
             # are not yet loaded:
 
             try:
+                index = occurrence - 1  # convert to 0-based index
+                if index < 0:  # basic validation
+                    self.logger.error("Occurrence must be >= 1")
+                    return None
                 self.logger.debug(
-                    "Wait for locator to find element with selector -> '%s' (%s%s%s) and state -> '%s'%s...",
+                    "Wait for locator to find %selement with selector -> '%s' (%s%s%s) and state -> '%s'%s...",
+                    "occurrence #{} of ".format(occurrence) if occurrence > 1 else "",
                     selector,
                     "selector type -> '{}'".format(selector_type),
                     ", role type -> '{}'".format(role_type) if role_type else "",
@@ -718,7 +773,9 @@ class BrowserAutomation:
                     wait_state,
                     " in iframe -> '{}'".format(iframe) if iframe else "",
                 )
-                locator = locator.first
+
+                locator = locator.first if occurrence == 1 else locator.nth(index)
+                # Wait for the element to be in the desired state:
                 locator.wait_for(state=wait_state)
             except PlaywrightError as pe:
                 if show_error and repeat_reload is None:
@@ -763,6 +820,7 @@ class BrowserAutomation:
         selector: str,
         selector_type: str = "id",
         role_type: str | None = None,
+        occurrence: int = 1,
         scroll_to_element: bool = True,
         desired_checkbox_state: bool | None = None,
         is_navigation_trigger: bool = False,
@@ -770,6 +828,7 @@ class BrowserAutomation:
         is_page_close_trigger: bool = False,
         wait_until: str | None = None,
         wait_time: float = 0.0,
+        wait_state: str = "visible",
         exact_match: bool | None = None,
         regex: bool = False,
         hover_only: bool = False,
@@ -793,6 +852,9 @@ class BrowserAutomation:
             role_type (str | None, optional):
                 ARIA role when using selector_type="role", e.g., "button", "textbox".
                 If irrelevant then None should be passed for role_type.
+            occurrence (int, optional):
+                If multiple elements match the selector, this defines which one to return.
+                Default is 1 (the first one).
             scroll_to_element (bool, optional):
                 Scroll the element into view.
             desired_checkbox_state (bool | None, optional):
@@ -814,8 +876,17 @@ class BrowserAutomation:
                   This seems to be the safest one for OpenText Content Server.
                 * "domcontentloaded" - waits for the DOMContentLoaded event (HTML is parsed,
                   but subresources may still load).
-            wait_time (float):
-                Time in seconds to wait for elements to appear.
+            wait_time (float, optional):
+                Time in seconds to wait for elements to appear. Default is 0.0 (no wait).
+            wait_state (str, optional):
+                Defines if we wait for attached (element is part of DOM) or
+                if we wait for elem to be visible (attached, displayed, and has non-zero size).
+                Possible values are:
+                * "attached" - the element is present in the DOM.
+                * "detached" - the element is not present in the DOM.
+                * "visible" - the element is visible (attached, displayed, and has non-zero size).
+                * "hidden" - the element is hidden (attached, but not displayed).
+                Default is "visible".
             exact_match (bool | None, optional):
                 If an exact matching is required. Default is None (not set).
             regex (bool, optional):
@@ -852,6 +923,14 @@ class BrowserAutomation:
 
         """
 
+        if not selector:
+            failure_message = "Missing element selector! Cannot find page element!"
+            if show_error:
+                self.logger.error(failure_message)
+            else:
+                self.logger.warning(failure_message)
+            return False
+
         success = True  # Final return value
 
         # If no specific wait until strategy is provided in the
@@ -865,20 +944,17 @@ class BrowserAutomation:
             self.logger.info("Wait for %d milliseconds before clicking...", wait_time * 1000)
             self.page.wait_for_timeout(wait_time * 1000)
 
-        if not selector:
-            failure_message = "Missing element selector! Cannot find page element!"
-            if show_error:
-                self.logger.error(failure_message)
-            else:
-                self.logger.warning(failure_message)
-            return False
+            if self.take_screenshots:
+                self.take_screenshot(suffix="_wait_before_click")
 
         elem = self.find_elem(
             selector=selector,
             selector_type=selector_type,
             role_type=role_type,
+            wait_state=wait_state,
             exact_match=exact_match,
             regex=regex,
+            occurrence=occurrence,
             iframe=iframe,
             repeat_reload=repeat_reload,
             repeat_reload_delay=repeat_reload_delay,
@@ -977,6 +1053,7 @@ class BrowserAutomation:
         value: str | bool,
         selector_type: str = "id",
         role_type: str | None = None,
+        occurrence: int = 1,
         is_sensitive: bool = False,
         press_enter: bool = False,
         exact_match: bool | None = None,
@@ -998,6 +1075,9 @@ class BrowserAutomation:
             role_type (str | None, optional):
                 ARIA role when using selector_type="role", e.g., "button", "textbox".
                 If irrelevant then None should be passed for role_type.
+            occurrence (int, optional):
+                If multiple elements match the selector, this defines which one to return.
+                Default is 1 (the first one).
             is_sensitive (bool, optional):
                 True for suppressing sensitive information in logging.
             press_enter (bool, optional):
@@ -1028,6 +1108,7 @@ class BrowserAutomation:
             role_type=role_type,
             exact_match=exact_match,
             regex=regex,
+            occurrence=occurrence,
             iframe=iframe,
             show_error=True,
         )
@@ -1172,7 +1253,7 @@ class BrowserAutomation:
             self.logger.error("Download failed; error -> %s", str(e))
             return None
 
-        self.logger.info("Download file to -> %s", save_path)
+        self.logger.info("Downloaded file to -> %s", save_path)
 
         return save_path
 
@@ -1223,13 +1304,13 @@ class BrowserAutomation:
                 Is the element in an iFrame? Then provide the name of the iframe with this parameter.
             min_count (int):
                 Minimum number of required matches (# elements on page).
-            wait_time (float):
-                Time in seconds to wait for elements to appear.
+            wait_time (float, optional):
+                Time in seconds to wait for elements to appear. Default is 0.0 (no wait).
             wait_state (str, optional):
                 Defines if we wait for attached (element is part of DOM) or
                 if we wait for elem to be visible (attached, displayed, and has non-zero size).
-            show_error (bool):
-                Whether to log warnings/errors.
+            show_error (bool, optional):
+                Whether to log warnings/errors. Default is True.
 
         Returns:
             bool | None:
@@ -1256,14 +1337,13 @@ class BrowserAutomation:
             iframe=iframe,
         )
         if not locator:
-            if show_error:
-                self.logger.error(
-                    "Failed to check if elements -> '%s' (%s) exist! Locator is undefined.", selector, selector_type
-                )
+            self.logger.error(
+                "Failed to check if elements -> '%s' (%s) exist! Locator is undefined.", selector, selector_type
+            )
             return (None, 0)
 
         self.logger.info(
-            "Check if at least %d element%s found by selector -> %s (%s%s)%s%s%s...",
+            "Check if at least %d element%s found by selector -> '%s' (%s%s)%s%s%s...",
             min_count,
             "s are" if min_count > 1 else " is",
             selector,
@@ -1319,8 +1399,9 @@ class BrowserAutomation:
             return (None, 0)
 
         self.logger.info(
-            "Found %s elements matching selector -> '%s' (%s%s).",
+            "Found %d element%s matching selector -> '%s' (%s%s).",
             count,
+            "s" if count > 1 else "",
             selector,
             "selector type -> '{}'".format(selector_type),
             ", role type -> '{}'".format(role_type) if role_type else "",
@@ -1336,7 +1417,7 @@ class BrowserAutomation:
 
         matching_elems = []
 
-        # Iterate over all elements found by the locator and checkif
+        # Iterate over all elements found by the locator and check if
         # they comply with the additional value conditions (if provided).
         # We collect all matching elements in a list:
         for i in range(count):
@@ -1374,8 +1455,9 @@ class BrowserAutomation:
         else:
             success = True
             self.logger.info(
-                "Found %d matching elements.%s",
+                "Found %d matching element%s.%s",
                 matching_elements_count,
+                "s" if matching_elements_count > 1 else "",
                 " This is {} the minimum {} element{} probed for.".format(
                     "exactly" if matching_elements_count == min_count else "more than",
                     min_count,
@@ -1467,7 +1549,7 @@ class BrowserAutomation:
             return False
 
         if "Verify" in title:
-            self.logger.error("Site is asking for a Verification Token. You may need to whitelist your IP!")
+            self.logger.error("Site is asking for a verification token. You may need to whitelist your IP!")
             return False
         if "Login" in title:
             self.logger.error("Authentication failed. You may have given the wrong password!")
@@ -1492,9 +1574,9 @@ class BrowserAutomation:
 
         """
 
-        self.logger.debug("Setting default timeout to -> %s seconds...", str(wait_time))
+        self.logger.debug("Setting default timeout to -> %.2f seconds...", wait_time)
         self.page.set_default_timeout(wait_time * 1000)
-        self.logger.debug("Setting navigation timeout to -> %s seconds...", str(wait_time))
+        self.logger.debug("Setting navigation timeout to -> %.2f seconds...", wait_time)
         self.page.set_default_navigation_timeout(wait_time * 1000)
 
     # end method definition
@@ -1502,11 +1584,11 @@ class BrowserAutomation:
     def end_session(self) -> None:
         """End the browser session and close the browser."""
 
-        self.logger.info("Close Browser Page...")
+        self.logger.info("Close browser page...")
         self.page.close()
-        self.logger.info("Close Browser Context...")
+        self.logger.info("Close browser context...")
         self.context.close()
-        self.logger.info("Close Browser...")
+        self.logger.info("Close browser...")
         self.browser.close()
         self.logged_in = False
         self.logger.info("Stop Playwright instance...")