pyxecm 2.0.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

{pyxecm/customizer → pyxecm_customizer}/browser_automation.py

@@ -59,6 +59,7 @@ __email__ = "mdiefenb@opentext.com"
 
 import logging
 import os
+import re
 import subprocess
 import tempfile
 import time
@@ -66,7 +67,7 @@ import traceback
 from http import HTTPStatus
 from types import TracebackType
 
-default_logger = logging.getLogger("pyxecm.customizer.browser_automation")
+default_logger = logging.getLogger("pyxecm_customizer.browser_automation")
 
 # For backwards compatibility we also want to handle
 # cases where the playwright modules have not been installed
@@ -151,7 +152,7 @@ class BrowserAutomation:
             download_directory = os.path.join(
                 tempfile.gettempdir(),
                 "browser_automations",
-                automation_name,
+                self.sanitize_filename(filename=automation_name),
                 "downloads",
             )
 
@@ -165,10 +166,11 @@ class BrowserAutomation:
         self.user_password = user_password
         self.logged_in = False
         self.download_directory = download_directory
+        self.headless = headless
 
         # Screenshot configurations:
         self.take_screenshots = take_screenshots
-        self.screenshot_names = automation_name
+        self.screenshot_names = self.sanitize_filename(filename=automation_name)
         self.screenshot_counter = 1
         self.screenshot_full_page = True
 
@@ -177,19 +179,16 @@ class BrowserAutomation:
         self.screenshot_directory = os.path.join(
             tempfile.gettempdir(),
             "browser_automations",
-            automation_name,
+            self.screenshot_names,
             "screenshots",
         )
         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.logger.debug("Creating Playwright instance...")
-        self.playwright = sync_playwright().start()
-
-        proxy = None
+        self.proxy = None
         if os.getenv("HTTP_PROXY"):
-            proxy = {
+            self.proxy = {
                 "server": os.getenv("HTTP_PROXY"),
             }
             self.logger.info("Using HTTP proxy -> %s", os.getenv("HTTP_PROXY"))
@@ -197,71 +196,110 @@ class BrowserAutomation:
         browser = browser or os.getenv("BROWSER", "webkit")
         self.logger.info("Using Browser -> '%s'...", browser)
 
+        if not self.setup_playwright(browser=browser):
+            self.logger.error("Failed to initialize Playwright browser automation!")
+            return
+
+        self.logger.info("Creating Browser Context...")
+        self.context: BrowserContext = self.browser.new_context(
+            accept_downloads=True,
+        )
+
+        self.logger.info("Creating Page...")
+        self.page: Page = self.context.new_page()
+        self.main_page = self.page
+        self.logger.info("Browser Automation initialized.")
+
+    # end method definition
+
+    def setup_playwright(self, browser: str) -> bool:
+        """Initialize Playwright browser automation.
+
+        Args:
+            browser (str):
+                Name of the browser engine.
+
+        Returns:
+            bool:
+                True = Success, False = Error.
+
+        """
+
+        try:
+            self.logger.debug("Creating Playwright instance...")
+            self.playwright = sync_playwright().start()
+        except Exception:
+            self.logger.error("Failed to start Playwright!")
+            return False
+
         match browser:
             case "chromium":
                 try:
                     self.browser: Browser = self.playwright.chromium.launch(
-                        headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        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=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
 
             case "chrome":
                 try:
                     self.browser: Browser = self.playwright.chromium.launch(
-                        channel="chrome", headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        channel="chrome",
+                        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(
-                        channel="chrome", headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        channel="chrome",
+                        headless=self.headless,
+                        slow_mo=100 if not self.headless else None,
+                        proxy=self.proxy,
                     )
 
             case "msedge":
                 try:
                     self.browser: Browser = self.playwright.chromium.launch(
-                        channel="msedge", headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        channel="msedge",
+                        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(
-                        channel="msedge", headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        channel="msedge",
+                        headless=self.headless,
+                        slow_mo=100 if not self.headless else None,
+                        proxy=self.proxy,
                     )
 
             case "webkit":
                 try:
                     self.browser: Browser = self.playwright.webkit.launch(
-                        headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        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=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
 
             case "firefox":
                 try:
                     self.browser: Browser = self.playwright.firefox.launch(
-                        headless=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        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=headless, slow_mo=100 if not headless else None, proxy=proxy
+                        headless=self.headless, slow_mo=100 if not self.headless else None, proxy=self.proxy
                     )
-
-        self.logger.info("Creating Browser Context...")
-        self.context: BrowserContext = self.browser.new_context(
-            accept_downloads=True,
-        )
-
-        self.logger.info("Creating Page...")
-        self.page: Page = self.context.new_page()
-        self.main_page = self.page
-        self.logger.info("Browser Automation initialized.")
+        return True
 
     # end method definition
 
@@ -287,6 +325,32 @@ class BrowserAutomation:
 
     # end method definition
 
+    def sanitize_filename(self, filename: str) -> str:
+        """Sanitize a string to be safe for use as a filename.
+
+        - Replaces spaces with underscores
+        - Removes unsafe characters
+        - Converts to lowercase
+        - Trims length and dots
+
+        Args:
+            filename (str):
+                The filename to sanitize.
+
+        """
+
+        filename = filename.lower()
+        filename = filename.replace(" ", "_")
+        filename = re.sub(r'[<>:"/\\|?*\x00-\x1F]', "", filename)  # Remove unsafe chars
+        filename = re.sub(r"\.+$", "", filename)  # Remove trailing dots
+        filename = filename.strip()
+        if not filename:
+            filename = "untitled"
+
+        return filename
+
+    # end method definition
+
     def take_screenshot(self) -> bool:
         """Take a screenshot of the current browser window and save it as PNG file.
 
@@ -438,17 +502,29 @@ class BrowserAutomation:
         """
 
         if not element:
-            self.logger.error("Undefined element!")
+            self.logger.error("Undefined element! Cannot scroll to it.")
             return
 
         try:
             element.scroll_into_view_if_needed()
         except PlaywrightError as e:
-            self.logger.error("Error while scrolling element into view -> %s", str(e))
+            self.logger.warning("Cannot scroll element -> %s into view; error -> %s", str(element), str(e))
 
     # end method definition
 
-    def get_locator(self, selector: str, selector_type: str, role_type: str | None = None) -> Locator | None:
+    def get_locator(
+        self,
+        selector: str,
+        selector_type: str,
+        role_type: str | None = None,
+        exact_match: bool | None = None,
+        iframe: str | None = None,
+        regex: bool = False,
+        filter_has_text: str | None = None,
+        filter_has: Locator | None = None,
+        filter_has_not_text: str | None = None,
+        filter_has_not: Locator | None = None,
+    ) -> Locator | None:
         """Determine the locator for the given selector type and (optional) role type.
 
         Args:
@@ -467,10 +543,27 @@ 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.
+            exact_match (bool | None, optional):
+                 Controls whether the text or name must match exactly.
+                 Default is None (not set, i.e. using playwrights default).
+            iframe (str | None):
+                Is the element in an iFrame? Then provide the name of the iframe with this parameter.
+            regex (bool, optional):
+                Should the name be interpreted as a regular expression?
+            filter_has_text (str | None, optional):
+                Applies `locator.filter(has_text=...)` to narrow the selection based on text content.
+            filter_has (Locator | None, optional):
+                Applies `locator.filter(has=...)` to match elements containing a descendant matching the given Locator.
+            filter_has_not_text (str | None, optional):
+                Applies `locator.filter(has_not_text=...)` to exclude elements with matching text content.
+            filter_has_not (Locator | None, optional):
+                Applies `locator.filter(has_not=...)` to exclude elements containing a matching descendant.
 
         """
 
         try:
+            name_or_text = re.compile(selector) if regex else selector
+
             match selector_type:
                 case "id":
                     locator = self.page.locator("#{}".format(selector))
@@ -481,27 +574,50 @@ class BrowserAutomation:
                 case "xpath":
                     locator = self.page.locator("xpath={}".format(selector))
                 case "css":
-                    locator = self.page.locator(selector)
+                    if iframe is None:
+                        locator = self.page.locator(selector)
+                    else:
+                        locator = self.page.locator("iframe[name='{}']".format(iframe)).content_frame.locator(selector)
                 case "text":
-                    #                    locator = self.page.get_by_text(selector)
-                    locator = self.page.locator("text={}".format(selector))
+                    if iframe is None:
+                        locator = self.page.get_by_text(text=name_or_text)
+                    else:
+                        locator = self.page.locator("iframe[name='{}']".format(iframe)).content_frame.get_by_text(
+                            name_or_text
+                        )
                 case "title":
-                    locator = self.page.get_by_title(selector)
+                    locator = self.page.get_by_title(text=name_or_text)
                 case "label":
-                    locator = self.page.get_by_label(selector)
+                    locator = self.page.get_by_label(text=name_or_text)
                 case "placeholder":
-                    locator = self.page.get_by_placeholder(selector)
+                    locator = self.page.get_by_placeholder(text=name_or_text)
                 case "alt":
-                    locator = self.page.get_by_alt_text(selector)
+                    locator = self.page.get_by_alt_text(text=name_or_text)
                 case "role":
                     if not role_type:
                         self.logger.error("Role type must be specified when using find method 'role'!")
                         return None
-                    locator = self.page.get_by_role(role=role_type, name=selector)
+                    if iframe is None:
+                        if regex:
+                            locator = self.page.get_by_role(role=role_type, name=name_or_text)
+                        else:
+                            locator = self.page.get_by_role(role=role_type, name=selector, exact=exact_match)
+                    else:
+                        content_frame = self.page.locator("iframe[name='{}']".format(iframe)).content_frame
+                        if regex:
+                            locator = content_frame.get_by_role(role=role_type, name=name_or_text)
+                        else:
+                            locator = content_frame.get_by_role(role=role_type, name=selector, exact=exact_match)
                 case _:
                     self.logger.error("Unsupported selector type -> '%s'", selector_type)
                     return None
 
+            # Apply filter if needed
+            if any([filter_has_text, filter_has, filter_has_not_text, filter_has_not]):
+                locator = locator.filter(
+                    has_text=filter_has_text, has=filter_has, has_not_text=filter_has_not_text, has_not=filter_has_not
+                )
+
         except PlaywrightError as e:
             self.logger.error("Failure to determine page locator; error -> %s", str(e))
             return None
@@ -516,6 +632,11 @@ class BrowserAutomation:
         selector_type: str = "id",
         role_type: str | None = None,
         wait_state: str = "visible",
+        exact_match: bool | None = None,
+        regex: bool = False,
+        iframe: str | None = None,
+        repeat_reload: int | None = None,
+        repeat_reload_delay: int = 60,
         show_error: bool = True,
     ) -> Locator | None:
         """Find a page element.
@@ -532,51 +653,106 @@ 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).
+            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?
+            iframe (str | None):
+                Is the element in an iFrame? Then provide the name of the iframe with this parameter.
+            repeat_reload (int | None):
+                For pages that are not dynamically updated and require a reload to show an update
+                a number of page reloads can be configured.
+            repeat_reload_delay (float | None):
+                Number of seconds to wait.
             show_error (bool, optional):
                 Show an error if not found or not visible.
 
+
         Returns:
             Locator:
                 The web element or None in case an error occured.
 
         """
 
-        failure_message = "Cannot find page element with selector -> '{}' ({}){}".format(
-            selector, selector_type, " and role type -> '{}'".format(role_type) if role_type else ""
+        failure_message = "Cannot find page element with selector -> '{}' ({}){}{}".format(
+            selector,
+            selector_type,
+            " and role type -> '{}'".format(role_type) if role_type else "",
+            " in iframe -> '{}'".format(iframe) if iframe else "",
         )
-        success_message = "Found page element with selector -> '{}' ('{}'){}".format(
-            selector, selector_type, " and role type -> '{}'".format(role_type) if role_type else ""
+        success_message = "Found page element with selector -> '{}' ('{}'){}{}".format(
+            selector,
+            selector_type,
+            " and role type -> '{}'".format(role_type) if role_type else "",
+            " in iframe -> '{}'".format(iframe) if iframe else "",
         )
 
-        # Determine the locator for the element:
-        locator = self.get_locator(selector=selector, selector_type=selector_type, role_type=role_type)
-        if not locator:
-            if show_error:
-                self.logger.error(failure_message)
+        def do_find() -> Locator | None:
+            # Determine the locator for the element:
+            locator = self.get_locator(
+                selector=selector,
+                selector_type=selector_type,
+                role_type=role_type,
+                exact_match=exact_match,
+                iframe=iframe,
+                regex=regex,
+            )
+            if not locator:
+                if show_error:
+                    self.logger.error(failure_message)
+                else:
+                    self.logger.warning(failure_message)
+                return None
+
+            # Wait for the element to be visible - don't use logic like
+            # locator.count() as this does not wait but fail immideately if elements
+            # are not yet loaded:
+
+            try:
+                self.logger.debug(
+                    "Wait for locator to find element with selector -> '%s' (%s%s%s) and state -> '%s'%s...",
+                    selector,
+                    "selector type -> '{}'".format(selector_type),
+                    ", role type -> '{}'".format(role_type) if role_type else "",
+                    ", using regular expression" if regex else "",
+                    wait_state,
+                    " in iframe -> '{}'".format(iframe) if iframe else "",
+                )
+                locator = locator.first
+                locator.wait_for(state=wait_state)
+            except PlaywrightError as pe:
+                if show_error and repeat_reload is None:
+                    self.logger.error("%s (%s)", failure_message, str(pe))
+                else:
+                    self.logger.warning("%s", failure_message)
+                return None
             else:
-                self.logger.warning(failure_message)
-            return None
+                self.logger.debug(success_message)
 
-        # Wait for the element to be visible - don't use logic like
-        # locator.count() as this does not wait but fail immideately if elements
-        # are not yet loaded:
-        try:
-            self.logger.info(
-                "Wait for locator to find element with selector -> '%s' (%s%s) and state -> '%s'...",
-                selector,
-                "selector type -> '{}'".format(selector_type),
-                ", role type -> '{}'".format(role_type) if role_type else "",
-                wait_state,
-            )
-            locator.wait_for(state=wait_state)
-        except PlaywrightError:
-            if show_error:
-                self.logger.error("%s (timeout)", failure_message)
+            return locator
+
+        # end def do_find():
+
+        locator = do_find()
+
+        # Retry logic for pages that are not updated dynamically:
+        if locator is None and repeat_reload is not None:
+            for i in range(repeat_reload):
+                self.logger.warning(
+                    "Wait %f seconds before reloading page -> %s to retrieve updates from server...",
+                    repeat_reload_delay,
+                    self.page.url,
+                )
+                time.sleep(repeat_reload_delay)
+                self.logger.warning(
+                    "Reloading page -> %s (retry %d) to retrieve updates from server...", self.page.url, i + 1
+                )
+                self.page.reload()
+                locator = do_find()
+                if locator:
+                    break
             else:
-                self.logger.warning("%s (timeout)", failure_message)
-            return None
-        else:
-            self.logger.debug(success_message)
+                self.logger.error(failure_message)
 
         return locator
 
@@ -594,6 +770,16 @@ class BrowserAutomation:
         is_page_close_trigger: bool = False,
         wait_until: str | None = None,
         wait_time: float = 0.0,
+        exact_match: bool | None = None,
+        regex: bool = False,
+        hover_only: bool = False,
+        iframe: str | None = None,
+        force: bool | None = None,
+        click_button: str | None = None,
+        click_count: int | None = None,
+        click_modifiers: list | None = None,
+        repeat_reload: int | None = None,
+        repeat_reload_delay: float = 60.0,
         show_error: bool = True,
     ) -> bool:
         """Find a page element and click it.
@@ -630,6 +816,32 @@ class BrowserAutomation:
                   but subresources may still load).
             wait_time (float):
                 Time in seconds to wait for elements to appear.
+            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?
+            hover_only (bool, optional):
+                Should we only hover over the element and not click it? Helpful for
+                menus that are opening on hovering.
+            iframe (str | None, optional):
+                Is the element in an iFrame? Then provide the name of the iframe with this parameter.
+            force (bool | None, optional):
+                If sure the element is interactable and visible (even partly), you can bypass visibility checks
+                by setting this option to True. Default is None (undefined, i.e. using the playwright default which is False)
+            click_button (Literal['left', 'middle', 'right'] | None, optional):
+                Which mouse button to use to do the click. The default is "left". This will be used by playwright if None
+                is passed.
+            click_count (int | None, optional):
+                Number of clicks. E.g. 2 for a "double-click".
+            click_modifiers (list | None, optional):
+                Key pressed together with the mouse click.
+                Possible values:'Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift'.
+                Default is None = no key pressed.
+            repeat_reload (int | None):
+                For pages that are not dynamically updated and require a reload to show an update
+                a number of page reloads can be configured.
+            repeat_reload_delay (float | None):
+                Number of seconds to wait.
             show_error (bool, optional):
                 Show an error if the element is not found or not clickable.
 
@@ -662,7 +874,15 @@ class BrowserAutomation:
             return False
 
         elem = self.find_elem(
-            selector=selector, selector_type=selector_type, role_type=role_type, show_error=show_error
+            selector=selector,
+            selector_type=selector_type,
+            role_type=role_type,
+            exact_match=exact_match,
+            regex=regex,
+            iframe=iframe,
+            repeat_reload=repeat_reload,
+            repeat_reload_delay=repeat_reload_delay,
+            show_error=show_error,
         )
         if not elem:
             return not show_error
@@ -680,7 +900,7 @@ class BrowserAutomation:
             else:
                 # Will this click trigger a naviagation?
                 if is_navigation_trigger:
-                    self.logger.info(
+                    self.logger.debug(
                         "Clicking on navigation-triggering element -> '%s' (%s%s) and wait until -> '%s'...",
                         selector,
                         "selector type -> '{}'".format(selector_type),
@@ -688,29 +908,38 @@ class BrowserAutomation:
                         wait_until,
                     )
                     with self.page.expect_navigation(wait_until=wait_until):
-                        elem.click()
+                        elem.click(force=force, button=click_button, click_count=click_count, modifiers=click_modifiers)
                 # Will this click trigger a a new popup window?
                 elif is_popup_trigger:
                     with self.page.expect_popup() as popup_info:
-                        elem.click()
+                        elem.click(force=force, button=click_button, click_count=click_count, modifiers=click_modifiers)
                     if not popup_info or not popup_info.value:
                         self.logger.info("Popup window did not open as expected!")
                         success = False
                     else:
                         self.page = popup_info.value
                         self.logger.info("Move browser automation to popup window -> %s...", self.page.url)
+                elif hover_only:
+                    self.logger.debug(
+                        "Hovering over element -> '%s' (%s%s)...",
+                        selector,
+                        "selector type -> '{}'".format(selector_type),
+                        ", role type -> '{}'".format(role_type) if role_type else "",
+                    )
+                    elem.hover()
                 else:
-                    self.logger.info(
+                    self.logger.debug(
                         "Clicking on non-navigating element -> '%s' (%s%s)...",
                         selector,
                         "selector type -> '{}'".format(selector_type),
                         ", role type -> '{}'".format(role_type) if role_type else "",
                     )
-                    elem.click()
+                    elem.click(force=force, button=click_button, click_count=click_count, modifiers=click_modifiers)
                     time.sleep(1)
                 if success:
                     self.logger.debug(
-                        "Successfully clicked element -> '%s' (%s%s)",
+                        "Successfully %s element -> '%s' (%s%s)",
+                        "clicked" if not hover_only else "hovered over",
                         selector,
                         "selector type -> '{}'".format(selector_type),
                         ", role type -> '{}'".format(role_type) if role_type else "",
@@ -749,6 +978,11 @@ class BrowserAutomation:
         selector_type: str = "id",
         role_type: str | None = None,
         is_sensitive: bool = False,
+        press_enter: bool = False,
+        exact_match: bool | None = None,
+        regex: bool = False,
+        iframe: str | None = None,
+        typing: bool = False,
         show_error: bool = True,
     ) -> bool:
         """Find an page element and fill it with a new text.
@@ -766,6 +1000,17 @@ class BrowserAutomation:
                 If irrelevant then None should be passed for role_type.
             is_sensitive (bool, optional):
                 True for suppressing sensitive information in logging.
+            press_enter (bool, optional):
+                Whether or not to press "Enter" after entering
+            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?
+            iframe (str | None):
+                Is the element in an iFrame? Then provide the name of the iframe with this parameter.
+            typing (bool, optional):
+                Not just set the value of the elem but simulate real typing.
+                This is required for pages with fields that do react in a "typeahead" manner.
             show_error (bool, optional):
                 Show an error if the element is not found or not clickable.
 
@@ -777,9 +1022,17 @@ class BrowserAutomation:
 
         success = False  # Final return value
 
-        elem = self.find_elem(selector=selector, selector_type=selector_type, role_type=role_type, show_error=True)
+        elem = self.find_elem(
+            selector=selector,
+            selector_type=selector_type,
+            role_type=role_type,
+            exact_match=exact_match,
+            regex=regex,
+            iframe=iframe,
+            show_error=True,
+        )
         if not elem:
-            return False
+            return not show_error
 
         is_enabled = elem.is_enabled()
         if not is_enabled:
@@ -837,7 +1090,12 @@ class BrowserAutomation:
 
                     success = retry < 5  # True is less than 5 retries were needed
             else:
-                elem.fill(value)
+                if typing:
+                    elem.type(value, delay=50)
+                else:
+                    elem.fill(value)
+                if press_enter:
+                    self.page.keyboard.press("Enter")
                 success = True
         except PlaywrightError as e:
             message = "Cannot set page element selected by -> '{}' ({}) to value -> '{}'; error -> {}".format(
@@ -861,6 +1119,9 @@ class BrowserAutomation:
         selector: str,
         selector_type: str = "id",
         role_type: str | None = None,
+        exact_match: bool | None = None,
+        regex: bool = False,
+        iframe: str | None = None,
         download_time: int = 30,
     ) -> str | None:
         """Click a page element to initiate a download.
@@ -874,6 +1135,12 @@ 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.
+            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?
+            iframe (str | None):
+                Is the element in an iFrame? Then provide the name of the iframe with this parameter.
             download_time (int, optional):
                 Time in seconds to wait for the download to complete.
 
@@ -885,7 +1152,14 @@ class BrowserAutomation:
 
         try:
             with self.page.expect_download(timeout=download_time * 1000) as download_info:
-                clicked = self.find_elem_and_click(selector=selector, selector_type=selector_type, role_type=role_type)
+                clicked = self.find_elem_and_click(
+                    selector=selector,
+                    selector_type=selector_type,
+                    role_type=role_type,
+                    exact_match=exact_match,
+                    regex=regex,
+                    iframe=iframe,
+                )
                 if not clicked:
                     self.logger.error("Element not found to initiate download.")
                     return None
@@ -910,8 +1184,10 @@ class BrowserAutomation:
         selector_type: str = "id",
         role_type: str | None = None,
         value: str | None = None,
+        exact_match: bool | None = None,
         attribute: str | None = None,
         substring: bool = True,
+        iframe: str | None = None,
         min_count: int = 1,
         wait_time: float = 0.0,
         wait_state: str = "visible",
@@ -937,10 +1213,14 @@ class BrowserAutomation:
                 If irrelevant then None should be passed for role_type.
             value (str, optional):
                 Value to match in attribute or element content.
+            exact_match (bool | None, optional):
+                If an exact matching is required. Default is None (not set).
             attribute (str, optional):
                 Attribute name to inspect. If None, uses element's text.
             substring (bool):
                 If True, allow partial match.
+            iframe (str | None):
+                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):
@@ -960,12 +1240,21 @@ class BrowserAutomation:
 
         """
 
-        failure_message = "No matching page element found with selector -> '{}' ({}){}".format(
-            selector, selector_type, " and role type -> '{}'".format(role_type) if role_type else ""
+        failure_message = "No matching page element found with selector -> '{}' ({}){}{}".format(
+            selector,
+            selector_type,
+            " and role type -> '{}'".format(role_type) if role_type else "",
+            " in iframe -> '{}'".format(iframe) if iframe else "",
         )
 
         # Determine the locator for the elements:
-        locator = self.get_locator(selector=selector, selector_type=selector_type, role_type=role_type)
+        locator = self.get_locator(
+            selector=selector,
+            selector_type=selector_type,
+            role_type=role_type,
+            exact_match=exact_match,
+            iframe=iframe,
+        )
         if not locator:
             if show_error:
                 self.logger.error(
@@ -974,7 +1263,7 @@ class BrowserAutomation:
             return (None, 0)
 
         self.logger.info(
-            "Check if at least %d element%s found by selector -> %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,
@@ -982,24 +1271,22 @@ class BrowserAutomation:
             ", role type -> {}".format(role_type) if role_type else "",
             " with value -> '{}'".format(value) if value else "",
             " in attribute -> '{}'".format(attribute) if attribute and value else "",
+            " in iframe -> '{}'".format(iframe) if iframe else "",
         )
 
         # Wait for the element to be visible - don't immediately use logic like
         # locator.count() as this does not wait but then fail immideately
         try:
             self.logger.info(
-                "Wait for locator to find first matching element with selector -> '%s' (%s%s) and state -> '%s'...",
+                "Wait for locator to find first matching element with selector -> '%s' (%s%s) and state -> '%s'%s...",
                 selector,
                 "selector type -> '{}'".format(selector_type),
                 ", role type -> {}".format(role_type) if role_type else "",
                 wait_state,
+                " in iframe -> '{}'".format(iframe) if iframe else "",
             )
             self.logger.info("Locator count before waiting: %d", locator.count())
 
-            # for i in range(locator.count()):
-            #     elem = locator.nth(i)
-            #     self.logger.info("Element #%d visible: %s", i, elem.is_visible())
-
             # IMPORTANT: We wait for the FIRST element. otherwise we get errors like
             # 'Locator.wait_for: Error: strict mode violation'.
             # IMPORTANT: if the first match does not comply to the
@@ -1021,12 +1308,14 @@ class BrowserAutomation:
             self.logger.info("Wait additional %d milliseconds before checking...", wait_time * 1000)
             self.page.wait_for_timeout(wait_time * 1000)
 
-        matching_elems = []
-
         count = locator.count()
         if count == 0:
             if show_error:
                 self.logger.error("No elements found using selector -> '%s' ('%s')", selector, selector_type)
+
+            if self.take_screenshots:
+                self.take_screenshot()
+
             return (None, 0)
 
         self.logger.info(
@@ -1045,13 +1334,18 @@ class BrowserAutomation:
                 value,
             )
 
+        matching_elems = []
+
+        # Iterate over all elements found by the locator and checkif
+        # they comply with the additional value conditions (if provided).
+        # We collect all matching elements in a list:
         for i in range(count):
             elem = locator.nth(i)
             if not elem:
                 continue
 
             if value is None:
-                # No filtering, accept all elements
+                # If value is None we do no filtering, accept all elements:
                 matching_elems.append(elem)
                 continue
 
@@ -1059,15 +1353,15 @@ class BrowserAutomation:
             attr_value = elem.get_attribute(attribute) if attribute else elem.text_content()
 
             if not attr_value:
+                # Nothing to compare with - continue:
                 continue
 
+            # If substring is True we check with "in" otherwise we use the eual operator (==):
             if (substring and value in attr_value) or (not substring and value == attr_value):
                 matching_elems.append(elem)
 
         matching_elements_count = len(matching_elems)
 
-        success = True
-
         if matching_elements_count < min_count:
             success = False
             if show_error:
@@ -1077,7 +1371,20 @@ class BrowserAutomation:
                     "s" if matching_elements_count > 1 else "",
                     min_count,
                 )
-        self.logger.info("Found %d matching elements.", matching_elements_count)
+        else:
+            success = True
+            self.logger.info(
+                "Found %d matching elements.%s",
+                matching_elements_count,
+                " This is {} the minimum {} element{} probed for.".format(
+                    "exactly" if matching_elements_count == min_count else "more than",
+                    min_count,
+                    "s" if min_count > 1 else "",
+                ),
+            )
+
+        if self.take_screenshots:
+            self.take_screenshot()
 
         return (success, matching_elements_count)
 
@@ -1119,7 +1426,8 @@ class BrowserAutomation:
                 Default is "id".
 
         Returns:
-            bool: True = success, False = error.
+            bool:
+                True = success, False = error.
 
         """
 
@@ -1147,7 +1455,7 @@ class BrowserAutomation:
             )
             return False
 
-        self.logger.info("Wait for -> '%s' to assure login is completed and target page is loaded.", wait_until)
+        self.logger.debug("Wait for -> '%s' to assure login is completed and target page is loaded.", wait_until)
         self.page.wait_for_load_state(wait_until)
 
         title = self.get_title()
@@ -1208,7 +1516,7 @@ class BrowserAutomation:
     # end method definition
 
     def __enter__(self) -> object:
-        """Enable use with 'with' statement."""
+        """Enable use with 'with' statement (context manager block)."""
 
         return self
 
@@ -1217,15 +1525,18 @@ class BrowserAutomation:
     def __exit__(
         self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback_obj: TracebackType | None
     ) -> None:
-        """Handle cleanup when exiting a context manager block.
+        """Handle cleanup when exiting a context manager block ('with' statement).
 
         Ensures all browser-related resources are released. If an unhandled exception
         occurs within the context block, it will be logged before cleanup.
 
         Args:
-            exc_type (type[BaseException] | None): The class of the raised exception, if any.
-            exc_value (BaseException | None): The exception instance raised, if any.
-            traceback_obj (TracebackType | None): The traceback object associated with the exception, if any.
+            exc_type (type[BaseException] | None):
+                The class of the raised exception, if any.
+            exc_value (BaseException | None):
+                The exception instance raised, if any.
+            traceback_obj (TracebackType | None):
+                The traceback object associated with the exception, if any.
 
         """