pyxecm 2.0.1__py3-none-any.whl → 2.0.3__py3-none-any.whl

pyxecm/customizer/browser_automation.py

@@ -5,6 +5,30 @@ These are typically used as fallback options if no REST API or LLConfig can be u
 This module uses playwright: https://playwright.dev for broweser-based automation
 and testing.
 
+Core Playwright data types and their relationships:
+
+Playwright
+ └── BrowserType (chromium / firefox / webkit)
+      └── Browser
+           └── BrowserContext
+                └── Page
+                     ├── Frame
+                     ├── Locator (preferred for element interactions)
+                     ├── ElementHandle (lower-level DOM reference)
+                     └── JSHandle (handle to any JS object)
+
+| Type               | Description                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **Playwright**     | Entry point via `sync_playwright()` or `async_playwright()`. Gives access to browser types.                    |
+| **BrowserType**    | Represents Chromium, Firefox, or WebKit. Used to launch a `Browser`.                                           |
+| **Browser**        | A running browser instance. Use `.new_context()` to create sessions.                                           |
+| **BrowserContext** | Isolated incognito-like browser profile. Contains pages.                                                       |
+| **Page**           | A single browser tab. Main interface for navigation and interaction.                                           |
+| **Frame**          | Represents a `<frame>` or `<iframe>`. Like a mini `Page`.                                                      |
+| **Locator**        | Lazily-evaluated, auto-waiting reference to one or more elements. **Preferred** for interacting with elements. |
+| **ElementHandle**  | Static reference to a single DOM element. Useful for special interactions or JS execution.                     |
+| **JSHandle**       | Handle to any JavaScript object, not just DOM nodes. Returned by `evaluate_handle()`.                          |
+
 Here are few few examples of the most typical page matches with the different selector types:
 
 | **Element to Match**     | **CSS**                        | **XPath**                                         | **Playwright `get_by_*` Method**          |
@@ -35,9 +59,12 @@ __email__ = "mdiefenb@opentext.com"
 
 import logging
 import os
+import subprocess
 import tempfile
 import time
+import traceback
 from http import HTTPStatus
+from types import TracebackType
 
 default_logger = logging.getLogger("pyxecm.customizer.browser_automation")
 
@@ -48,7 +75,7 @@ try:
     from playwright.sync_api import (
         Browser,
         BrowserContext,
-        ElementHandle,
+        Locator,
         Page,
         sync_playwright,
     )
@@ -66,6 +93,7 @@ REQUEST_TIMEOUT = 30
 REQUEST_RETRY_DELAY = 2
 REQUEST_MAX_RETRIES = 3
 
+
 class BrowserAutomation:
     """Class to automate settings via a browser interface."""
 
@@ -82,6 +110,7 @@ class BrowserAutomation:
         headless: bool = True,
         logger: logging.Logger = default_logger,
         wait_until: str | None = None,
+        browser: str | None = None,
     ) -> None:
         """Initialize the object.
 
@@ -106,12 +135,15 @@ class BrowserAutomation:
                 If True, the browser will be started in headless mode. Defaults to True.
             wait_until (str | None, optional):
                 Wait until a certain condition. Options are:
-                * "load" - Waits for the load event (after all resources like images/scripts load)
-                * "networkidle" - Waits until there are no network connections for at least 500 ms.
-                * "domcontentloaded" - Waits for the DOMContentLoaded event (HTML is parsed,
+                * "commit" - does not wait at all - commit the request and continue
+                * "load" - waits for the load event (after all resources like images/scripts load)
+                * "networkidle" - waits until there are no network connections for at least 500 ms.
+                * "domcontentloaded" - waits for the DOMContentLoaded event (HTML is parsed,
                   but subresources may still load).
             logger (logging.Logger, optional):
                 The logging object to use for all log messages. Defaults to default_logger.
+            browser (str | None, optional):
+                The browser to use. Defaults to None, which takes the global default or from the ENV "BROWSER".
 
         """
 
@@ -134,9 +166,12 @@ class BrowserAutomation:
         self.logged_in = False
         self.download_directory = download_directory
 
+        # Screenshot configurations:
         self.take_screenshots = take_screenshots
         self.screenshot_names = automation_name
         self.screenshot_counter = 1
+        self.screenshot_full_page = True
+
         self.wait_until = wait_until if wait_until else DEFAULT_WAIT_UNTIL_STRATEGY
 
         self.screenshot_directory = os.path.join(
@@ -145,15 +180,110 @@ class BrowserAutomation:
             automation_name,
             "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()
-        self.browser: Browser = self.playwright.chromium.launch(headless=headless)
+
+        proxy = None
+        if os.getenv("HTTP_PROXY"):
+            proxy = {
+                "server": os.getenv("HTTP_PROXY"),
+            }
+            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)
+
+        match browser:
+            case "chromium":
+                try:
+                    self.browser: Browser = self.playwright.chromium.launch(
+                        headless=headless, slow_mo=100 if not headless else None, proxy=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
+                    )
+
+            case "chrome":
+                try:
+                    self.browser: Browser = self.playwright.chromium.launch(
+                        channel="chrome", headless=headless, slow_mo=100 if not headless else None, proxy=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
+                    )
+
+            case "msedge":
+                try:
+                    self.browser: Browser = self.playwright.chromium.launch(
+                        channel="msedge", headless=headless, slow_mo=100 if not headless else None, proxy=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
+                    )
+
+            case "webkit":
+                try:
+                    self.browser: Browser = self.playwright.webkit.launch(
+                        headless=headless, slow_mo=100 if not headless else None, proxy=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
+                    )
+
+            case "firefox":
+                try:
+                    self.browser: Browser = self.playwright.firefox.launch(
+                        headless=headless, slow_mo=100 if not headless else None, proxy=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
+                    )
+
+        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 install_browser(self, browser: str) -> bool:
+        """Check if browser is already installed if not install it."""
+
+        self.logger.info("Installing Browser -> '%s'...", browser)
+        process = subprocess.Popen(
+            ["playwright", "install", browser],  # noqa: S607
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            shell=False,
+        )
+        output, error = process.communicate()
+        if process.returncode == 0:
+            self.logger.info("Installation completed successfullly.")
+            self.logger.debug(output.decode())
+        else:
+            self.logger.error("Installation failed with -> %s", error.decode())
+            self.logger.error(output.decode())
+
+        return True
 
     # end method definition
 
@@ -166,7 +296,7 @@ class BrowserAutomation:
 
         """
 
-        screenshot_file = "{}/{}-{}.png".format(
+        screenshot_file = "{}/{}-{:02d}.png".format(
             self.screenshot_directory,
             self.screenshot_names,
             self.screenshot_counter,
@@ -174,7 +304,7 @@ class BrowserAutomation:
         self.logger.debug("Save browser screenshot to -> %s", screenshot_file)
 
         try:
-            self.page.screenshot(path=screenshot_file)
+            self.page.screenshot(path=screenshot_file, full_page=self.screenshot_full_page)
             self.screenshot_counter += 1
         except Exception as e:
             self.logger.error("Failed to take screenshot; error -> %s", e)
@@ -192,12 +322,13 @@ class BrowserAutomation:
                 URL to load. If empty just the base URL will be used.
             wait_until (str | None, optional):
                 Wait until a certain condition. Options are:
-                * "load" - Waits for the load event (after all resources like images/scripts load)
+                * "commit" - does not wait at all - commit the request and continue
+                * "load" - waits for the load event (after all resources like images/scripts load)
                   This is the safest strategy for pages that keep loading content in the background
                   like Salesforce.
-                * "networkidle" - Waits until there are no network connections for at least 500 ms.
+                * "networkidle" - waits until there are no network connections for at least 500 ms.
                   This seems to be the safest one for OpenText Content Server.
-                * "domcontentloaded" - Waits for the DOMContentLoaded event (HTML is parsed,
+                * "domcontentloaded" - waits for the DOMContentLoaded event (HTML is parsed,
                   but subresources may still load).
 
         Returns:
@@ -214,7 +345,7 @@ class BrowserAutomation:
         page_url = self.base_url + url
 
         try:
-            self.logger.debug("Load page -> %s", page_url)
+            self.logger.debug("Load page -> %s (wait until -> '%s')", page_url, wait_until)
 
             # The Playwright Response object is different from the requests.response object!
             response = self.page.goto(page_url, wait_until=wait_until)
@@ -258,38 +389,50 @@ class BrowserAutomation:
         Args:
             wait_until (str | None, optional):
                 Wait until a certain condition. Options are:
-                * "load" - Waits for the load event (after all resources like images/scripts load)
+                * "commit" - does not wait at all - commit the request and continue
+                * "load" - waits for the load event (after all resources like images/scripts load)
                   This is the safest strategy for pages that keep loading content in the background
                   like Salesforce.
-                * "networkidle" - Waits until there are no network connections for at least 500 ms.
+                * "networkidle" - waits until there are no network connections for at least 500 ms.
                   This seems to be the safest one for OpenText Content Server.
-                * "domcontentloaded" - Waits for the DOMContentLoaded event (HTML is parsed,
+                * "domcontentloaded" - waits for the DOMContentLoaded event (HTML is parsed,
                   but subresources may still load).
 
         Returns:
             str:
-                The title of the browser window.
+                The title of the browser page.
 
         """
 
-        for _ in range(REQUEST_MAX_RETRIES):
+        for attempt in range(REQUEST_MAX_RETRIES):
             try:
-                return self.page.title()
+                if wait_until:
+                    self.page.wait_for_load_state(state=wait_until, timeout=REQUEST_TIMEOUT)
+                title = self.page.title()
+                if title:
+                    return title
+                time.sleep(REQUEST_RETRY_DELAY)
+                self.logger.info("Retry attempt %d/%d", attempt + 1, REQUEST_MAX_RETRIES)
             except Exception as e:
                 if "Execution context was destroyed" in str(e):
+                    self.logger.info(
+                        "Execution context was destroyed, retrying after %s seconds...", REQUEST_RETRY_DELAY
+                    )
                     time.sleep(REQUEST_RETRY_DELAY)
-                    self.page.wait_for_load_state(state=wait_until, timeout=REQUEST_TIMEOUT)
-                else:
-                    self.logger.error("Could not get page title; error -> %s", e)
+                    self.logger.info("Retry attempt %d/%d", attempt + 1, REQUEST_MAX_RETRIES)
+                    continue
+                self.logger.error("Could not get page title; error -> %s", str(e))
+                break
 
         return None
+
     # end method definition
 
-    def scroll_to_element(self, element: ElementHandle) -> None:
+    def scroll_to_element(self, element: Locator) -> None:
         """Scroll an element into view to make it clickable.
 
         Args:
-            element (ElementHandle):
+            element (Locator):
                 Web element that has been identified before.
 
         """
@@ -305,41 +448,28 @@ class BrowserAutomation:
 
     # end method definition
 
-    def find_elem(
-        self,
-        selector: str,
-        selector_type: str = "id",
-        role_type: str | None = None,
-        show_error: bool = True,
-    ) -> ElementHandle | None:
-        """Find a page element.
+    def get_locator(self, selector: str, selector_type: str, role_type: str | None = None) -> Locator | None:
+        """Determine the locator for the given selector type and (optional) role type.
 
         Args:
             selector (str):
-                The name of the page element or accessible name (for role).
-            selector_type (str, optional):
+                The selector to find the element on the page.
+            selector_type (str):
                 One of "id", "name", "class_name", "xpath", "css", "role", "text", "title",
                 "label", "placeholder", "alt".
+                When using css, the selector becomes a raw CSS selector, and you can skip attribute
+                and value filtering entirely if your selector already narrows it down.
+                Examples for CSS:
+                * selector="img" - find all img tags (images)
+                * selector="img[title]" - find all img tags (images) that have a title attribute - independent of its value
+                * selector="img[title*='Microsoft Teams']" - find all images with a title that contains "Microsoft Teams"
+                * selector=".toolbar button" - find all buttons inside a .toolbar class
             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.
-            show_error (bool, optional):
-                Show an error if not found or not visible.
-
-        Returns:
-            ElementHandle:
-                The web element or None in case an error occured.
 
         """
 
-        locator = None
-        failure_message = "Cannot find 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 ""
-        )
-
         try:
             match selector_type:
                 case "id":
@@ -353,7 +483,8 @@ class BrowserAutomation:
                 case "css":
                     locator = self.page.locator(selector)
                 case "text":
-                    locator = self.page.get_by_text(selector)
+                    #                    locator = self.page.get_by_text(selector)
+                    locator = self.page.locator("text={}".format(selector))
                 case "title":
                     locator = self.page.get_by_title(selector)
                 case "label":
@@ -371,23 +502,83 @@ class BrowserAutomation:
                     self.logger.error("Unsupported selector type -> '%s'", selector_type)
                     return None
 
-            elem = locator.element_handle() if locator is not None else None
-            if elem is None:
-                if show_error:
-                    self.logger.error(failure_message)
-                else:
-                    self.logger.warning(failure_message)
+        except PlaywrightError as e:
+            self.logger.error("Failure to determine page locator; error -> %s", str(e))
+            return None
+
+        return locator
+
+    # end method definition
+
+    def find_elem(
+        self,
+        selector: str,
+        selector_type: str = "id",
+        role_type: str | None = None,
+        wait_state: str = "visible",
+        show_error: bool = True,
+    ) -> Locator | None:
+        """Find a page element.
+
+        Args:
+            selector (str):
+                The name of the page element or accessible name (for role).
+            selector_type (str, optional):
+                One of "id", "name", "class_name", "xpath", "css", "role", "text", "title",
+                "label", "placeholder", "alt".
+            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.
+            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, 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 ""
+        )
+        success_message = "Found page element with selector -> '{}' ('{}'){}".format(
+            selector, selector_type, " and role type -> '{}'".format(role_type) if role_type 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)
             else:
-                self.logger.debug(success_message)
+                self.logger.warning(failure_message)
+            return None
 
-        except PlaywrightError as e:
+        # 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; error -> %s", failure_message, str(e))
+                self.logger.error("%s (timeout)", failure_message)
             else:
-                self.logger.warning("%s; error -> %s", failure_message, str(e))
+                self.logger.warning("%s (timeout)", failure_message)
             return None
+        else:
+            self.logger.debug(success_message)
 
-        return elem
+        return locator
 
     # end method definition
 
@@ -399,7 +590,10 @@ class BrowserAutomation:
         scroll_to_element: bool = True,
         desired_checkbox_state: bool | None = None,
         is_navigation_trigger: bool = False,
+        is_popup_trigger: bool = False,
+        is_page_close_trigger: bool = False,
         wait_until: str | None = None,
+        wait_time: float = 0.0,
         show_error: bool = True,
     ) -> bool:
         """Find a page element and click it.
@@ -420,15 +614,22 @@ class BrowserAutomation:
                 If None then click it in any case.
             is_navigation_trigger (bool, optional):
                 Is the click causing a navigation. Default is False.
+            is_popup_trigger (bool, optional):
+                Is the click causing a new browser window to open?
+            is_page_close_trigger (bool, optional):
+                Is the click causing the page to close?
             wait_until (str | None, optional):
                 Wait until a certain condition. Options are:
-                * "load" - Waits for the load event (after all resources like images/scripts load)
+                * "commit" - does not wait at all - commit the request and continue
+                * "load" - waits for the load event (after all resources like images/scripts load)
                   This is the safest strategy for pages that keep loading content in the background
                   like Salesforce.
-                * "networkidle" - Waits until there are no network connections for at least 500 ms.
+                * "networkidle" - waits until there are no network connections for at least 500 ms.
                   This seems to be the safest one for OpenText Content Server.
-                * "domcontentloaded" - Waits for the DOMContentLoaded event (HTML is parsed,
+                * "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.
             show_error (bool, optional):
                 Show an error if the element is not found or not clickable.
 
@@ -439,11 +640,19 @@ class BrowserAutomation:
 
         """
 
+        success = True  # Final return value
+
         # If no specific wait until strategy is provided in the
         # parameter, we take the one from the browser automation class:
         if wait_until is None:
             wait_until = self.wait_until
 
+        # Some operations that are done server-side and dynamically update
+        # the page may require a waiting time:
+        if wait_time > 0.0:
+            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:
@@ -462,74 +671,74 @@ class BrowserAutomation:
             if scroll_to_element:
                 self.scroll_to_element(elem)
 
-            # Handle checkboxes
-            is_checkbox = elem.get_attribute("type") == "checkbox"
-            checkbox_state = None
-
-            if is_checkbox and desired_checkbox_state is not None:
-                checkbox_state = elem.is_checked()
-                if checkbox_state == desired_checkbox_state:
-                    self.logger.debug(
-                        "Checkbox -> '%s' is already in desired state -> %s", selector, desired_checkbox_state
+            # Handle checkboxes if requested:
+            if desired_checkbox_state is not None and elem.get_attribute("type") == "checkbox":
+                # Let Playwright handle checkbox state:
+                elem.set_checked(desired_checkbox_state)
+                self.logger.debug("Set checkbox -> '%s' to value -> %s.", selector, desired_checkbox_state)
+            # Handle non-checkboxes:
+            else:
+                # Will this click trigger a naviagation?
+                if is_navigation_trigger:
+                    self.logger.info(
+                        "Clicking on navigation-triggering element -> '%s' (%s%s) and wait until -> '%s'...",
+                        selector,
+                        "selector type -> '{}'".format(selector_type),
+                        ", role type -> '{}'".format(role_type) if role_type else "",
+                        wait_until,
                     )
-                    return True  # No need to click
-                else:
-                    self.logger.debug("Checkbox -> '%s' has state mismatch. Clicking to change state.", selector)
-
-            if is_navigation_trigger:
-                self.logger.info("Clicking on navigation-triggering element -> '%s'", selector)
-                try:
                     with self.page.expect_navigation(wait_until=wait_until):
                         elem.click()
-                except PlaywrightError as e:
-                    self.logger.error(
-                        "Navigation after clicking on element -> '%s' did not happen or failed; likely wrong parameter passed; error -> %s",
+                # Will this click trigger a a new popup window?
+                elif is_popup_trigger:
+                    with self.page.expect_popup() as popup_info:
+                        elem.click()
+                    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)
+                else:
+                    self.logger.info(
+                        "Clicking on non-navigating element -> '%s' (%s%s)...",
                         selector,
-                        str(e),
+                        "selector type -> '{}'".format(selector_type),
+                        ", role type -> '{}'".format(role_type) if role_type else "",
                     )
-                    return False
-            else:
-                self.logger.info("Clicking on non-navigating element -> '%s'", selector)
-                try:
                     elem.click()
                     time.sleep(1)
-                except PlaywrightError as e:
-                    self.logger.error("Click failed -> %s", str(e))
-                    return False
-
-            if is_checkbox and desired_checkbox_state is not None:
-                elem = self.find_elem(selector=selector, selector_type=selector_type, show_error=show_error)
-                if elem:
-                    checkbox_state = elem.is_checked()
-
-            if checkbox_state is not None:
-                if checkbox_state == desired_checkbox_state:
+                if success:
                     self.logger.debug(
-                        "Successfully clicked checkbox element -> '%s'. It's state is now -> %s",
+                        "Successfully clicked element -> '%s' (%s%s)",
                         selector,
-                        checkbox_state,
+                        "selector type -> '{}'".format(selector_type),
+                        ", role type -> '{}'".format(role_type) if role_type else "",
                     )
-                else:
-                    self.logger.error(
-                        "Failed to flip checkbox element -> '%s' to desired state. It's state is still -> %s and not -> %s",
-                        selector,
-                        checkbox_state,
-                        desired_checkbox_state,
-                    )
-            else:
-                self.logger.debug("Successfully clicked element -> '%s'", selector)
-
-            if self.take_screenshots:
-                self.take_screenshot()
 
         except PlaywrightError as e:
             if show_error:
-                self.logger.error("Cannot click page element -> '%s'; error -> %s", selector, str(e))
+                self.logger.error(
+                    "Cannot click page element -> '%s' (%s); error -> %s", selector, selector_type, str(e)
+                )
             else:
-                self.logger.warning("Cannot click page element -> '%s'; warning -> %s", selector, str(e))
-            return not show_error
+                self.logger.warning(
+                    "Cannot click page element -> '%s' (%s); warning -> %s", selector, selector_type, str(e)
+                )
+            success = not show_error
 
-        return True
+        if is_page_close_trigger:
+            if self.page == self.main_page:
+                self.logger.error("Unexpected try to close main page! Popup page not active! This is not supported!")
+                success = False
+            else:
+                self.page = self.main_page
+                self.logger.info("Move browser automation back to main window -> %s...", self.page.url)
+
+        if self.take_screenshots:
+            self.take_screenshot()
+
+        return success
 
     # end method definition
 
@@ -566,6 +775,8 @@ class BrowserAutomation:
 
         """
 
+        success = False  # Final return value
+
         elem = self.find_elem(selector=selector, selector_type=selector_type, role_type=role_type, show_error=True)
         if not elem:
             return False
@@ -580,12 +791,14 @@ class BrowserAutomation:
             else:
                 self.logger.warning(message)
 
+            if self.take_screenshots:
+                self.take_screenshot()
+
             return False
 
-        if not is_sensitive:
-            self.logger.debug("Set element -> %s to value -> '%s'...", selector, value)
-        else:
-            self.logger.debug("Set element -> %s to value -> <sensitive>...", selector)
+        self.logger.info(
+            "Set element -> '%s' to value -> '%s'...", selector, value if not is_sensitive else "<sensitive>"
+        )
 
         try:
             # HTML '<select>' can only be identified based on its tag name:
@@ -594,27 +807,38 @@ class BrowserAutomation:
             input_type = elem.get_attribute("type")
 
             if tag_name == "select":
-                options = elem.query_selector_all("option")
-                option_values = [opt.inner_text().strip().replace("\n", "") for opt in options]
+                options = elem.locator("option")
+                options_count = options.count()
+                option_values = [options.nth(i).inner_text().strip().replace("\n", "") for i in range(options_count)]
+
                 if value not in option_values:
                     self.logger.warning(
-                        "Provided value -> '%s' not in available drop-down options -> %s. Cannot set it!",
+                        "Provided value -> '%s' is not in available drop-down options -> %s. Cannot set it!",
                         value,
                         option_values,
                     )
-                    return False
-                # We set the value over the (visible) label:
-                elem.select_option(label=value)
+                else:
+                    # We set the value over the (visible) label:
+                    elem.select_option(label=value)
+                    success = True
             elif tag_name == "input" and input_type == "checkbox":
                 # Handle checkbox
                 if not isinstance(value, bool):
                     self.logger.error("Checkbox value must be a boolean!")
-                    return False
-                is_checked = elem.is_checked()
-                if value != is_checked:
-                    elem.check() if value else elem.uncheck()
+                else:
+                    retry = 0
+                    while elem.is_checked() != value and retry < 5:
+                        try:
+                            elem.set_checked(checked=value)
+                        except Exception:
+                            self.logger.warning("Cannot set checkbox to value -> '%s'. (retry %s).", value, retry)
+                        finally:
+                            retry += 1
+
+                    success = retry < 5  # True is less than 5 retries were needed
             else:
                 elem.fill(value)
+                success = True
         except PlaywrightError as e:
             message = "Cannot set page element selected by -> '{}' ({}) to value -> '{}'; error -> {}".format(
                 selector, selector_type, value, str(e)
@@ -623,12 +847,12 @@ class BrowserAutomation:
                 self.logger.error(message)
             else:
                 self.logger.warning(message)
-            return False
+            success = not show_error
 
         if self.take_screenshots:
             self.take_screenshot()
 
-        return True
+        return success
 
     # end method definition
 
@@ -690,13 +914,14 @@ class BrowserAutomation:
         substring: bool = True,
         min_count: int = 1,
         wait_time: float = 0.0,
+        wait_state: str = "visible",
         show_error: bool = True,
     ) -> tuple[bool | None, int]:
         """Check if (multiple) elements with defined attributes exist on page and return the number.
 
         Args:
             selector (str):
-                Base selector.
+                The selector to find the element on the page.
             selector_type (str):
                 One of "id", "name", "class_name", "xpath", "css", "role", "text", "title",
                 "label", "placeholder", "alt".
@@ -720,6 +945,9 @@ class BrowserAutomation:
                 Minimum number of required matches (# elements on page).
             wait_time (float):
                 Time in seconds to wait for elements to appear.
+            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.
 
@@ -732,86 +960,126 @@ 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 ""
+        )
+
+        # Determine the locator for the elements:
+        locator = self.get_locator(selector=selector, selector_type=selector_type, role_type=role_type)
+        if not locator:
+            if show_error:
+                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...",
+            min_count,
+            "s are" if min_count > 1 else " is",
+            selector,
+            "selector type -> '{}'".format(selector_type),
+            ", 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 "",
+        )
+
+        # 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'...",
+                selector,
+                "selector type -> '{}'".format(selector_type),
+                ", role type -> {}".format(role_type) if role_type else "",
+                wait_state,
+            )
+            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
+            # wait_state this will block and then timeout. Check your
+            # selector to make sure it delivers a visible first element!
+            locator.first.wait_for(state=wait_state)
+        except PlaywrightError as e:
+            # This is typically a timeout error indicating the element does not exist
+            # in the defined timeout period.
+            if show_error:
+                self.logger.error("%s (timeout); error -> %s", failure_message, str(e))
+            else:
+                self.logger.warning("%s (timeout)", failure_message)
+            return (None, 0)
+
         # Some operations that are done server-side and dynamically update
-        # the page may require a waiting time:
+        # the page with additional matching elements that may require a waiting time:
         if wait_time > 0.0:
-            self.logger.info("Wait for %d milliseconds before checking...", wait_time * 1000)
+            self.logger.info("Wait additional %d milliseconds before checking...", wait_time * 1000)
             self.page.wait_for_timeout(wait_time * 1000)
 
-        try:
-            match selector_type:
-                case "id":
-                    locator = self.page.locator("#{}".format(selector))
-                case "name":
-                    locator = self.page.locator("[name='{}']".format(selector))
-                case "class_name":
-                    locator = self.page.locator(".{}".format(selector))
-                case "xpath":
-                    locator = self.page.locator("xpath={}".format(selector))
-                case "css":
-                    locator = self.page.locator(selector)
-                case "text":
-                    locator = self.page.get_by_text(selector)
-                case "title":
-                    locator = self.page.get_by_title(selector)
-                case "label":
-                    locator = self.page.get_by_label(selector)
-                case "placeholder":
-                    locator = self.page.get_by_placeholder(selector)
-                case "alt":
-                    locator = self.page.get_by_alt_text(selector)
-                case "role":
-                    if not role_type:
-                        self.logger.error("Role type must be specified when using find method 'role'!")
-                        return (None, 0)
-                    locator = self.page.get_by_role(role=role_type, name=selector)
-                case _:
-                    self.logger.error("Unsupported selector type -> '%s'", selector_type)
-                    return (None, 0)
+        matching_elems = []
 
-            matching_elems = []
+        count = locator.count()
+        if count == 0:
+            if show_error:
+                self.logger.error("No elements found using selector -> '%s' ('%s')", selector, selector_type)
+            return (None, 0)
 
-            count = locator.count() if locator is not None else 0
-            if count == 0:
-                if show_error:
-                    self.logger.error("No elements found using selector -> '%s' ('%s')", selector, selector_type)
-                return (None, 0)
+        self.logger.info(
+            "Found %s elements matching selector -> '%s' (%s%s).",
+            count,
+            selector,
+            "selector type -> '{}'".format(selector_type),
+            ", role type -> '{}'".format(role_type) if role_type else "",
+        )
 
-            for i in range(count):
-                elem_handle = locator.nth(i).element_handle()
-                if not elem_handle:
-                    continue
+        if value:
+            self.logger.info(
+                "Checking if their %s %s -> '%s'...",
+                "attribute -> '{}'".format(attribute) if attribute else "content",
+                "has value" if not substring else "contains",
+                value,
+            )
 
-                if value is None:
-                    # No filtering, accept all elements
-                    matching_elems.append(elem_handle)
-                    continue
+        for i in range(count):
+            elem = locator.nth(i)
+            if not elem:
+                continue
 
-                # Get attribute or text content
-                attr_value = elem_handle.get_attribute(attribute) if attribute else elem_handle.text_content()
+            if value is None:
+                # No filtering, accept all elements
+                matching_elems.append(elem)
+                continue
 
-                if not attr_value:
-                    continue
+            # Get attribute or text content
+            attr_value = elem.get_attribute(attribute) if attribute else elem.text_content()
 
-                if (substring and value in attr_value) or (not substring and value == attr_value):
-                    matching_elems.append(elem_handle)
+            if not attr_value:
+                continue
 
-            matching_elements_count = len(matching_elems)
+            if (substring and value in attr_value) or (not substring and value == attr_value):
+                matching_elems.append(elem)
 
-            if matching_elements_count < min_count and show_error:
-                self.logger.warning(
-                    "%s matching elements found, expected at least %d",
+        matching_elements_count = len(matching_elems)
+
+        success = True
+
+        if matching_elements_count < min_count:
+            success = False
+            if show_error:
+                self.logger.error(
+                    "%s matching element%s found, expected at least %d",
                     "Only {}".format(matching_elements_count) if matching_elems else "No",
+                    "s" if matching_elements_count > 1 else "",
                     min_count,
                 )
-                return (False, matching_elements_count)
+        self.logger.info("Found %d matching elements.", matching_elements_count)
 
-        except PlaywrightError as e:
-            if show_error:
-                self.logger.error("Failed to check if elements -> '%s' exist; errors -> %s", selector, str(e))
-            return (None, 0)
-
-        return (True, matching_elements_count)
+        return (success, matching_elements_count)
 
     # end method definition
 
@@ -837,12 +1105,13 @@ class BrowserAutomation:
                 The URL to the login page. Defaults to "".
             wait_until (str | None, optional):
                 Wait until a certain condition. Options are:
-                * "load" - Waits for the load event (after all resources like images/scripts load)
+                * "commit" - does not wait at all - commit the request and continue
+                * "load" - waits for the load event (after all resources like images/scripts load)
                   This is the safest strategy for pages that keep loading content in the background
                   like Salesforce.
-                * "networkidle" - Waits until there are no network connections for at least 500 ms.
+                * "networkidle" - waits until there are no network connections for at least 500 ms.
                   This seems to be the safest one for OpenText Content Server.
-                * "domcontentloaded" - Waits for the DOMContentLoaded event (HTML is parsed,
+                * "domcontentloaded" - waits for the DOMContentLoaded event (HTML is parsed,
                   but subresources may still load).
             selector_type (str, optional):
                 One of "id", "name", "class_name", "xpath", "css", "role", "text", "title",
@@ -878,16 +1147,17 @@ class BrowserAutomation:
             )
             return False
 
+        self.logger.info("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()
         if not title:
             self.logger.error(
-                "Cannot read page title after login - you may have the wrong 'wait until' strategy configured!",
+                "Cannot read page title after login - you may have the wrong 'wait until' strategy configured! Strategy user -> '%s'.",
+                wait_until,
             )
             return False
 
-
         if "Verify" in title:
             self.logger.error("Site is asking for a Verification Token. You may need to whitelist your IP!")
             return False
@@ -895,6 +1165,7 @@ class BrowserAutomation:
             self.logger.error("Authentication failed. You may have given the wrong password!")
             return False
 
+        self.logger.info("Login completed successfully! Page title -> '%s'", title)
         self.logged_in = True
 
         return True
@@ -923,10 +1194,47 @@ class BrowserAutomation:
     def end_session(self) -> None:
         """End the browser session and close the browser."""
 
-        self.logger.debug("Ending browser automation session...")
+        self.logger.info("Close Browser Page...")
+        self.page.close()
+        self.logger.info("Close Browser Context...")
         self.context.close()
+        self.logger.info("Close Browser...")
         self.browser.close()
         self.logged_in = False
+        self.logger.info("Stop Playwright instance...")
         self.playwright.stop()
+        self.logger.info("Browser automation has ended.")
+
+    # end method definition
+
+    def __enter__(self) -> object:
+        """Enable use with 'with' statement."""
+
+        return self
+
+    # end method definition
+
+    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.
+
+        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.
+
+        """
+
+        if exc_type is not None:
+            self.logger.error(
+                "Unhandled exception in browser automation context -> %s",
+                "".join(traceback.format_exception(exc_type, exc_value, traceback_obj)),
+            )
+
+        self.end_session()
 
     # end method definition