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

pyxecm/customizer/browser_automation.py

@@ -1,6 +1,30 @@
 """browser_automation Module to automate configuration via a browser interface.
 
 These are typically used as fallback options if no REST API or LLConfig can be used.
+
+This module uses playwright: https://playwright.dev for broweser-based automation
+and testing.
+
+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**          |
+| ------------------------ | ------------------------------ | ------------------------------------------------- | ----------------------------------------- |
+| Element with ID          | `#myId`                        | `//*[@id='myId']`                                 | *Not available directly; use `locator()`* |
+| Element with class       | `.myClass`                     | `//*[@class='myClass']`                           | *Not available directly; use `locator()`* |
+| Button with exact text   | `button:has-text("Submit")`    | `//button[text()='Submit']`                       | `get_by_role("button", name="Submit")`    |
+| Button with partial text | `button:has-text("Sub")`       | `//button[contains(text(), 'Sub')]`               | `get_by_text("Sub")`                      |
+| Input with name          | `input[name="email"]`          | `//input[@name='email']`                          | *Not available directly; use `locator()`* |
+| Link by text             | `a:has-text("Home")`           | `//a[text()='Home']`                              | `get_by_role("link", name="Home")`        |
+| Element with title       | `[title="Info"]`               | `//*[@title='Info']`                              | `get_by_title("Info")`                    |
+| Placeholder text         | `input[placeholder="Search"]`  | `//input[@placeholder='Search']`                  | `get_by_placeholder("Search")`            |
+| Label text (form input)  | `label:has-text("Email")`      | `//label[text()='Email']`                         | `get_by_label("Email")`                   |
+| Alt text (image)         | `img[alt="Logo"]`              | `//img[@alt='Logo']`                              | `get_by_alt_text("Logo")`                 |
+| Role and name (ARIA)     | `[role="button"][name="Save"]` | `//*[@role='button' and @name='Save']`            | `get_by_role("button", name="Save")`      |
+| Visible text anywhere    | `:text("Welcome")`             | `//*[contains(text(), "Welcome")]`                | `get_by_text("Welcome")`                  |
+| nth element in a list    | `ul > li:nth-child(2)`         | `(//ul/li)[2]`                                    | `locator("ul > li").nth(1)`               |
+| Element with attribute   | `[data-test-id="main"]`        | `//*[@data-test-id='main']`                       | *Not available directly; use `locator()`* |
+| Nested element           | `.container .button`           | `//div[@class='container']//div[@class='button']` | `locator(".container .button")`           |
+
 """
 
 __author__ = "Dr. Marc Diefenbruch"
@@ -9,57 +33,38 @@ __credits__ = ["Kai-Philip Gatzweiler"]
 __maintainer__ = "Dr. Marc Diefenbruch"
 __email__ = "mdiefenb@opentext.com"
 
-
 import logging
 import os
 import tempfile
 import time
-
-import urllib3
+from http import HTTPStatus
 
 default_logger = logging.getLogger("pyxecm.customizer.browser_automation")
 
 # For backwards compatibility we also want to handle
-# cases where the selenium and chromedriver_autoinstaller
-# modules have not been installed in the customizer container:
+# cases where the playwright modules have not been installed
+# in the customizer container:
 try:
-    from selenium import webdriver
-    from selenium.common.exceptions import (
-        ElementClickInterceptedException,
-        ElementNotInteractableException,
-        InvalidElementStateException,
-        MoveTargetOutOfBoundsException,
-        NoSuchElementException,
-        StaleElementReferenceException,
-        TimeoutException,
-        WebDriverException,
+    from playwright.sync_api import (
+        Browser,
+        BrowserContext,
+        ElementHandle,
+        Page,
+        sync_playwright,
     )
-    from selenium.webdriver.chrome.options import Options
-    from selenium.webdriver.common.action_chains import ActionChains
-    from selenium.webdriver.common.by import By
-    from selenium.webdriver.remote.webelement import WebElement
-    from selenium.webdriver.support.ui import Select
-
+    from playwright.sync_api import Error as PlaywrightError
 except ModuleNotFoundError:
-    default_logger.warning("Module selenium is not installed")
-
-    class Options:
-        """Dummy class to avoid errors if selenium module cannot be imported."""
-
-    class By:
-        """Dummy class to avoid errors if selenium module cannot be imported."""
-
-        ID: str = ""
-
-    class WebElement:
-        """Dummy class to avoid errors if selenium module cannot be imported."""
-
+    default_logger.warning("Module playwright is not installed")
 
-try:
-    import chromedriver_autoinstaller
-except ModuleNotFoundError:
-    default_logger.warning("Module chromedriver_autoinstaller is not installed!")
+# We use "networkidle" as default "wait until" strategy as
+# this seems to best harmonize with OTCS. Especially login
+# procedure for OTDS / OTCS seems to not work with the "load"
+# "wait until" strategy.
+DEFAULT_WAIT_UNTIL_STRATEGY = "networkidle"
 
+REQUEST_TIMEOUT = 30
+REQUEST_RETRY_DELAY = 2
+REQUEST_MAX_RETRIES = 3
 
 class BrowserAutomation:
     """Class to automate settings via a browser interface."""
@@ -74,14 +79,16 @@ class BrowserAutomation:
         download_directory: str | None = None,
         take_screenshots: bool = False,
         automation_name: str = "",
+        headless: bool = True,
         logger: logging.Logger = default_logger,
+        wait_until: str | None = None,
     ) -> None:
         """Initialize the object.
 
         Args:
             base_url (str, optional):
                 The base URL of the website to automate. Defaults to "".
-            user_name (str, optional): _description_. Defaults to "".
+            user_name (str, optional):
                 If an authentication at the web site is required, this is the user name.
                 Defaults to "".
             user_password (str, optional):
@@ -94,7 +101,15 @@ class BrowserAutomation:
                 For debugging purposes, screenshots can be taken.
                 Defaults to False.
             automation_name (str, optional):
-                The name of the automation. Defaults to "screen".
+                The name of the automation. Defaults to "".
+            headless (bool, optional):
+                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,
+                  but subresources may still load).
             logger (logging.Logger, optional):
                 The logging object to use for all log messages. Defaults to default_logger.
 
@@ -121,7 +136,8 @@ class BrowserAutomation:
 
         self.take_screenshots = take_screenshots
         self.screenshot_names = automation_name
-        self.screen_counter = 1
+        self.screenshot_counter = 1
+        self.wait_until = wait_until if wait_until else DEFAULT_WAIT_UNTIL_STRATEGY
 
         self.screenshot_directory = os.path.join(
             tempfile.gettempdir(),
@@ -129,50 +145,15 @@ class BrowserAutomation:
             automation_name,
             "screenshots",
         )
-
         if self.take_screenshots and not os.path.exists(self.screenshot_directory):
             os.makedirs(self.screenshot_directory)
-        chromedriver_autoinstaller.install()
-        self.browser = webdriver.Chrome(options=self.set_chrome_options())
-
-    # end method definition
-
-    def __del__(self) -> None:
-        """Object destructor."""
-
-        try:
-            if self.browser:
-                self.browser.quit()
-                self.browser = None
-        except (WebDriverException, AttributeError, TypeError, OSError):
-            # Log or silently handle exceptions during interpreter shutdown
-            pass
-
-    # end method definition
 
-    def set_chrome_options(self) -> Options:
-        """Set chrome options for Selenium.
-
-        Chrome options for headless browser is enabled.
-
-        Returns:
-            Options: Options to call the browser with
-
-        """
-
-        chrome_options = Options()
-        chrome_options.add_argument("--headless")
-        chrome_options.add_argument("--no-sandbox")
-        chrome_options.add_argument("--disable-dev-shm-usage")
-        chrome_prefs = {}
-        chrome_options.experimental_options["prefs"] = chrome_prefs
-
-        chrome_options.add_experimental_option(
-            "prefs",
-            {"download.default_directory": self.download_directory},
+        self.playwright = sync_playwright().start()
+        self.browser: Browser = self.playwright.chromium.launch(headless=headless)
+        self.context: BrowserContext = self.browser.new_context(
+            accept_downloads=True,
         )
-
-        return chrome_options
+        self.page: Page = self.context.new_page()
 
     # end method definition
 
@@ -188,75 +169,127 @@ class BrowserAutomation:
         screenshot_file = "{}/{}-{}.png".format(
             self.screenshot_directory,
             self.screenshot_names,
-            self.screen_counter,
+            self.screenshot_counter,
         )
         self.logger.debug("Save browser screenshot to -> %s", screenshot_file)
-        result = self.browser.get_screenshot_as_file(screenshot_file)
-        self.screen_counter += 1
 
-        return result
+        try:
+            self.page.screenshot(path=screenshot_file)
+            self.screenshot_counter += 1
+        except Exception as e:
+            self.logger.error("Failed to take screenshot; error -> %s", e)
+            return False
+
+        return True
 
-    def get_page(self, url: str = "") -> bool:
+    # end method definition
+
+    def get_page(self, url: str = "", wait_until: str | None = None) -> bool:
         """Load a page into the browser based on a given URL.
 
         Args:
             url (str):
-                URL to load. If empty just the base URL will be used
+                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)
+                  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.
+                  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).
+
         Returns:
             bool:
-                True if successful, False otherwise
+                True if successful, False otherwise.
 
         """
 
+        # 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
+
         page_url = self.base_url + url
 
         try:
             self.logger.debug("Load page -> %s", page_url)
-            self.browser.get(page_url)
 
-        except (WebDriverException, urllib3.exceptions.ReadTimeoutError):
-            self.logger.error(
-                "Cannot load page -> %s!",
-                page_url,
-            )
-            return False
+            # The Playwright Response object is different from the requests.response object!
+            response = self.page.goto(page_url, wait_until=wait_until)
+            if response is None:
+                self.logger.warning("Loading of page -> %s completed but no response object was returned.", page_url)
+            elif not response.ok:
+                # Try to get standard phrase, fall back if unknown
+                try:
+                    phrase = HTTPStatus(response.status).phrase
+                except ValueError:
+                    phrase = "Unknown Status"
+                self.logger.error(
+                    "Response for page -> %s is not OK. Status -> %s/%s",
+                    page_url,
+                    response.status,
+                    phrase,
+                )
+                return False
 
-        self.logger.debug("Page title after get page -> %s", self.browser.title)
+        except PlaywrightError as e:
+            self.logger.error("Navigation to page -> %s has failed; error -> %s", page_url, str(e))
+            return False
 
         if self.take_screenshots:
             self.take_screenshot()
 
-        # Wait a second before proceeding
-        time.sleep(1)
-
         return True
 
     # end method definition
 
-    def get_title(self) -> str:
+    def get_title(
+        self,
+        wait_until: str | None = None,
+    ) -> str | None:
         """Get the browser title.
 
         This is handy to validate a certain page is loaded after get_page()
 
+        Retry-safe way to get the page title, even if there's an in-flight navigation.
+
+        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)
+                  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.
+                  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).
+
         Returns:
             str:
                 The title of the browser window.
 
         """
 
-        if not self.browser:
-            self.logger.error("Browser not initialized!")
-            return None
-
-        return self.browser.title
+        for _ in range(REQUEST_MAX_RETRIES):
+            try:
+                return self.page.title()
+            except Exception as e:
+                if "Execution context was destroyed" in str(e):
+                    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)
 
+        return None
     # end method definition
 
-    def scroll_to_element(self, element: WebElement) -> None:
+    def scroll_to_element(self, element: ElementHandle) -> None:
         """Scroll an element into view to make it clickable.
 
         Args:
-            element (WebElement):
+            element (ElementHandle):
                 Web element that has been identified before.
 
         """
@@ -266,92 +299,93 @@ class BrowserAutomation:
             return
 
         try:
-            actions = ActionChains(self.browser)
-            actions.move_to_element(element).perform()
-        except NoSuchElementException:
-            self.logger.error("Element not found in the DOM!")
-        except TimeoutException:
-            self.logger.error(
-                "Timed out waiting for the element to be present or visible!",
-            )
-        except ElementNotInteractableException:
-            self.logger.error("Element is not interactable!")
-        except MoveTargetOutOfBoundsException:
-            self.logger.error("Element is out of bounds!")
-        except WebDriverException:
-            self.logger.error("WebDriverException occurred!")
+            element.scroll_into_view_if_needed()
+        except PlaywrightError as e:
+            self.logger.error("Error while scrolling element into view -> %s", str(e))
 
     # end method definition
 
     def find_elem(
         self,
-        find_elem: str,
-        find_method: str = By.ID,
+        selector: str,
+        selector_type: str = "id",
+        role_type: str | None = None,
         show_error: bool = True,
-    ) -> WebElement:
-        """Find an page element.
+    ) -> ElementHandle | None:
+        """Find a page element.
 
         Args:
-            find_elem (str):
-                The name of the page element.
-            find_method (str, optional):
-                Either By.ID, By.NAME, By.CLASS_NAME, BY.XPATH
+            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.
             show_error (bool, optional):
-                Show an error if the element is not found or not clickable.
+                Show an error if not found or not visible.
 
         Returns:
-            WebElement:
+            ElementHandle:
                 The web element or None in case an error occured.
 
         """
 
-        # We don't want to expose class "By" outside this module,
-        # so we map the string values to the By class values:
-        if find_method == "id":
-            find_method = By.ID
-        elif find_method == "name":
-            find_method = By.NAME
-        elif find_method == "class_name":
-            find_method = By.CLASS_NAME
-        elif find_method == "xpath":
-            find_method = By.XPATH
-        else:
-            self.logger.error("Unsupported find method!")
-            return None
+        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:
-            elem = self.browser.find_element(by=find_method, value=find_elem)
-        except NoSuchElementException:
+            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
+                    locator = self.page.get_by_role(role=role_type, name=selector)
+                case _:
+                    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)
+            else:
+                self.logger.debug(success_message)
+
+        except PlaywrightError as e:
             if show_error:
-                self.logger.error(
-                    "Cannot find page element -> %s by -> %s",
-                    find_elem,
-                    find_method,
-                )
-                return None
+                self.logger.error("%s; error -> %s", failure_message, str(e))
             else:
-                self.logger.warning(
-                    "Cannot find page element -> %s by -> %s",
-                    find_elem,
-                    find_method,
-                )
-                return None
-        except TimeoutException:
-            self.logger.error(
-                "Timed out waiting for the element to be present or visible!",
-            )
-            return None
-        except ElementNotInteractableException:
-            self.logger.error("Element is not interactable!")
-            return None
-        except MoveTargetOutOfBoundsException:
-            self.logger.error("Element is out of bounds!")
+                self.logger.warning("%s; error -> %s", failure_message, str(e))
             return None
-        except WebDriverException:
-            self.logger.error("WebDriverException occurred!")
-            return None
-
-        self.logger.debug("Found page element -> %s by -> %s", find_elem, find_method)
 
         return elem
 
@@ -359,24 +393,42 @@ class BrowserAutomation:
 
     def find_elem_and_click(
         self,
-        find_elem: str,
-        find_method: str = By.ID,
+        selector: str,
+        selector_type: str = "id",
+        role_type: str | None = None,
         scroll_to_element: bool = True,
         desired_checkbox_state: bool | None = None,
+        is_navigation_trigger: bool = False,
+        wait_until: str | None = None,
         show_error: bool = True,
     ) -> bool:
-        """Find an page element and click it.
+        """Find a page element and click it.
 
         Args:
-            find_elem (str):
-                The identifier of the page element.
-            find_method (str, optional):
-                Either By.ID, By.NAME, By.CLASS_NAME, BY.XPATH
+            selector (str):
+                The selector of the page element.
+            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.
             scroll_to_element (bool, optional):
                 Scroll the element into view.
             desired_checkbox_state (bool | None, optional):
                 If True/False, ensures checkbox matches state.
                 If None then click it in any case.
+            is_navigation_trigger (bool, optional):
+                Is the click causing a navigation. Default is False.
+            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)
+                  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.
+                  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).
             show_error (bool, optional):
                 Show an error if the element is not found or not clickable.
 
@@ -387,99 +439,95 @@ class BrowserAutomation:
 
         """
 
-        if not find_elem:
+        # 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
+
+        if not selector:
+            failure_message = "Missing element selector! Cannot find page element!"
             if show_error:
-                self.logger.error("Missing element name! Cannot find HTML element!")
+                self.logger.error(failure_message)
             else:
-                self.logger.warning("Missing element name! Cannot find HTML element!")
+                self.logger.warning(failure_message)
             return False
 
         elem = self.find_elem(
-            find_elem=find_elem,
-            find_method=find_method,
-            show_error=show_error,
+            selector=selector, selector_type=selector_type, role_type=role_type, show_error=show_error
         )
-
         if not elem:
             return not show_error
 
-        is_checkbox = elem.get_attribute("type") == "checkbox"
-        checkbox_state = None
-
         try:
             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_selected()
+                checkbox_state = elem.is_checked()
                 if checkbox_state == desired_checkbox_state:
                     self.logger.debug(
-                        "Checkbox -> '%s' already in desired state -> %s",
-                        find_elem,
-                        desired_checkbox_state,
+                        "Checkbox -> '%s' is already in desired state -> %s", selector, desired_checkbox_state
                     )
                     return True  # No need to click
                 else:
-                    self.logger.debug("Checkbox -> '%s' state mismatch. Clicking to change state.", find_elem)
+                    self.logger.debug("Checkbox -> '%s' has state mismatch. Clicking to change state.", selector)
 
-            elem.click()
-            time.sleep(1)
+            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",
+                        selector,
+                        str(e),
+                    )
+                    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
 
-            # Handle checkboxes
             if is_checkbox and desired_checkbox_state is not None:
-                # Re-locate the element after clicking to avoid stale reference
-                elem = self.find_elem(
-                    find_elem=find_elem,
-                    find_method=find_method,
-                    show_error=show_error,
-                )
-                # Is the element still there?
+                elem = self.find_elem(selector=selector, selector_type=selector_type, show_error=show_error)
                 if elem:
-                    checkbox_state = elem.is_selected() if is_checkbox else None
+                    checkbox_state = elem.is_checked()
 
-        except (
-            ElementClickInterceptedException,
-            ElementNotInteractableException,
-            StaleElementReferenceException,
-            InvalidElementStateException,
-        ):
-            if show_error:
-                self.logger.error(
-                    "Cannot click page element -> %s!",
-                    find_elem,
-                )
-                return False
+            if checkbox_state is not None:
+                if checkbox_state == desired_checkbox_state:
+                    self.logger.debug(
+                        "Successfully clicked checkbox element -> '%s'. It's state is now -> %s",
+                        selector,
+                        checkbox_state,
+                    )
+                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.warning("Cannot click page element -> %s", find_elem)
-                return True
-        except TimeoutException:
-            if show_error:
-                self.logger.error("Timeout waiting for element -> %s to be clickable!", find_elem)
-            return not show_error
+                self.logger.debug("Successfully clicked element -> '%s'", selector)
 
-        if checkbox_state is not None:
-            if checkbox_state == desired_checkbox_state:
-                self.logger.debug(
-                    "Successfully clicked checkbox element -> %s. It's state is now -> %s",
-                    find_elem,
-                    checkbox_state,
-                )
-            else:
-                self.logger.error(
-                    "Failed to flip checkbox element -> %s to desired state. It's state is still -> %s and not -> %s",
-                    find_elem,
-                    checkbox_state,
-                    desired_checkbox_state,
-                )
-        else:
-            self.logger.debug(
-                "Successfully clicked element -> %s",
-                find_elem,
-            )
+            if self.take_screenshots:
+                self.take_screenshot()
 
-        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))
+            else:
+                self.logger.warning("Cannot click page element -> '%s'; warning -> %s", selector, str(e))
+            return not show_error
 
         return True
 
@@ -487,63 +535,94 @@ class BrowserAutomation:
 
     def find_elem_and_set(
         self,
-        find_elem: str,
-        elem_value: str,
-        find_method: str = By.ID,
+        selector: str,
+        value: str | bool,
+        selector_type: str = "id",
+        role_type: str | None = None,
         is_sensitive: bool = False,
+        show_error: bool = True,
     ) -> bool:
         """Find an page element and fill it with a new text.
 
         Args:
-            find_elem (str): name of the page element
-            elem_value (str): new text string for the page element
-            find_method (str, optional): either By.ID, By.NAME, By.CLASS_NAME, or By.XPATH
-            is_sensitive (bool, optional): True for suppressing sensitive information in logging
+            selector (str):
+                The name of the page element.
+            value (str | bool):
+                The new value (text string) for the page element.
+            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.
+            is_sensitive (bool, optional):
+                True for suppressing sensitive information in logging.
+            show_error (bool, optional):
+                Show an error if the element is not found or not clickable.
+
         Returns:
-            bool: True if successful, False otherwise
+            bool:
+                True if successful, False otherwise
 
         """
 
-        elem = self.find_elem(
-            find_elem=find_elem,
-            find_method=find_method,
-            show_error=True,
-        )
-
+        elem = self.find_elem(selector=selector, selector_type=selector_type, role_type=role_type, show_error=True)
         if not elem:
             return False
 
-        if not elem.is_enabled():
-            self.logger.error("Cannot set elem -> %s to value -> %s. It is not enabled!", find_elem, elem_value)
+        is_enabled = elem.is_enabled()
+        if not is_enabled:
+            message = "Cannot set elem -> '{}' ({}) to value -> '{}'. It is not enabled!".format(
+                selector, selector_type, value
+            )
+            if show_error:
+                self.logger.error(message)
+            else:
+                self.logger.warning(message)
+
             return False
 
         if not is_sensitive:
-            self.logger.debug(
-                "Set element -> %s to value -> %s...",
-                find_elem,
-                elem_value,
-            )
+            self.logger.debug("Set element -> %s to value -> '%s'...", selector, value)
         else:
-            self.logger.debug("Set element -> %s to value -> <sensitive>...", find_elem)
+            self.logger.debug("Set element -> %s to value -> <sensitive>...", selector)
 
         try:
-            # Check if element is a drop-down (select element)
-            if elem.tag_name.lower() == "select":
-                select = Select(elem)
-                try:
-                    select.select_by_visible_text(elem_value)  # Select option by visible text
-                except NoSuchElementException:
-                    self.logger.error("Option -> '%s' not found in drop-down -> '%s'", elem_value, find_elem)
+            # HTML '<select>' can only be identified based on its tag name:
+            tag_name = elem.evaluate("el => el.tagName.toLowerCase()")
+            # Checkboxes have tag name '<input type="checkbox">':
+            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]
+                if value not in option_values:
+                    self.logger.warning(
+                        "Provided value -> '%s' 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)
+            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:
-                elem.clear()  # clear existing text in the input field
-                elem.send_keys(elem_value)  # write new text into the field
-        except (ElementNotInteractableException, InvalidElementStateException):
-            self.logger.error(
-                "Cannot set page element -> %s to value -> %s",
-                find_elem,
-                elem_value,
+                elem.fill(value)
+        except PlaywrightError as e:
+            message = "Cannot set page element selected by -> '{}' ({}) to value -> '{}'; error -> {}".format(
+                selector, selector_type, value, str(e)
             )
+            if show_error:
+                self.logger.error(message)
+            else:
+                self.logger.warning(message)
             return False
 
         if self.take_screenshots:
@@ -555,45 +634,184 @@ class BrowserAutomation:
 
     def find_element_and_download(
         self,
-        find_elem: str,
-        find_method: str = By.ID,
+        selector: str,
+        selector_type: str = "id",
+        role_type: str | None = None,
         download_time: int = 30,
     ) -> str | None:
         """Click a page element to initiate a download.
 
         Args:
-            find_elem (str):
+            selector (str):
                 The page element to click for download.
-            find_method (str, optional):
-                A method to find the element. Defaults to By.ID.
+            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.
             download_time (int, optional):
-                Time in seconds to wait for the download to complete
+                Time in seconds to wait for the download to complete.
 
         Returns:
             str | None:
-                The filename of the download.
+                The full file path of the downloaded file.
 
         """
 
-        # Record the list of files in the download directory before the download
-        initial_files = set(os.listdir(self.download_directory))
-
-        if not self.find_elem_and_click(
-            find_elem=find_elem,
-            find_method=find_method,
-        ):
+        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)
+                if not clicked:
+                    self.logger.error("Element not found to initiate download.")
+                    return None
+
+            download = download_info.value
+            filename = download.suggested_filename
+            save_path = os.path.join(self.download_directory, filename)
+            download.save_as(save_path)
+        except Exception as e:
+            self.logger.error("Download failed; error -> %s", str(e))
             return None
 
-        # Wait for the download to complete
-        self.browser.implicitly_wait(download_time)
+        self.logger.info("Download file to -> %s", save_path)
+
+        return save_path
+
+    # end method definition
+
+    def check_elems_exist(
+        self,
+        selector: str,
+        selector_type: str = "id",
+        role_type: str | None = None,
+        value: str | None = None,
+        attribute: str | None = None,
+        substring: bool = True,
+        min_count: int = 1,
+        wait_time: float = 0.0,
+        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.
+            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.
+            value (str, optional):
+                Value to match in attribute or element content.
+            attribute (str, optional):
+                Attribute name to inspect. If None, uses element's text.
+            substring (bool):
+                If True, allow partial match.
+            min_count (int):
+                Minimum number of required matches (# elements on page).
+            wait_time (float):
+                Time in seconds to wait for elements to appear.
+            show_error (bool):
+                Whether to log warnings/errors.
+
+        Returns:
+            bool | None:
+                True if sufficient elements exist. False otherwise.
+                None if an error occurs.
+            int:
+                Number of matched elements.
+
+        """
 
-        # Record the list of files in the download directory after the download
-        current_files = set(os.listdir(self.download_directory))
+        # 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 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 = []
+
+            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)
+
+            for i in range(count):
+                elem_handle = locator.nth(i).element_handle()
+                if not elem_handle:
+                    continue
+
+                if value is None:
+                    # No filtering, accept all elements
+                    matching_elems.append(elem_handle)
+                    continue
+
+                # Get attribute or text content
+                attr_value = elem_handle.get_attribute(attribute) if attribute else elem_handle.text_content()
+
+                if not attr_value:
+                    continue
+
+                if (substring and value in attr_value) or (not substring and value == attr_value):
+                    matching_elems.append(elem_handle)
+
+            matching_elements_count = len(matching_elems)
+
+            if matching_elements_count < min_count and show_error:
+                self.logger.warning(
+                    "%s matching elements found, expected at least %d",
+                    "Only {}".format(matching_elements_count) if matching_elems else "No",
+                    min_count,
+                )
+                return (False, matching_elements_count)
 
-        # Determine the name of the downloaded file
-        new_file = (current_files - initial_files).pop()
+        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 new_file
+        return (True, matching_elements_count)
 
     # end method definition
 
@@ -603,6 +821,8 @@ class BrowserAutomation:
         password_field: str = "otds_password",
         login_button: str = "loginbutton",
         page: str = "",
+        wait_until: str | None = None,
+        selector_type: str = "id",
     ) -> bool:
         """Login to target system via the browser.
 
@@ -615,48 +835,64 @@ class BrowserAutomation:
                 The name of the HTML login button. Defaults to "loginbutton".
             page (str, optional):
                 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)
+                  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.
+                  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).
+            selector_type (str, optional):
+                One of "id", "name", "class_name", "xpath", "css", "role", "text", "title",
+                "label", "placeholder", "alt".
+                Default is "id".
 
         Returns:
             bool: True = success, False = error.
 
         """
 
+        # 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
+
         self.logged_in = False
 
         if (
-            not self.get_page(
-                url=page,
-            )  # assuming the base URL leads towards the login page
+            not self.get_page(url=page, wait_until=wait_until)
+            or not self.find_elem_and_set(selector=user_field, selector_type=selector_type, value=self.user_name)
             or not self.find_elem_and_set(
-                find_elem=user_field,
-                elem_value=self.user_name,
+                selector=password_field, selector_type=selector_type, value=self.user_password, is_sensitive=True
             )
-            or not self.find_elem_and_set(
-                find_elem=password_field,
-                elem_value=self.user_password,
-                is_sensitive=True,
+            or not self.find_elem_and_click(
+                selector=login_button, selector_type=selector_type, is_navigation_trigger=True, wait_until=wait_until
             )
-            or not self.find_elem_and_click(find_elem=login_button)
         ):
             self.logger.error(
-                "Cannot log into target system using URL -> %s and user -> %s",
+                "Cannot log into target system using URL -> %s and user -> '%s'!",
                 self.base_url,
                 self.user_name,
             )
             return False
 
-        self.logger.debug("Page title after login -> %s", self.browser.title)
+        self.page.wait_for_load_state(wait_until)
 
-        # Some special handling for Salesforce login:
-        if "Verify" in self.browser.title:
+        title = self.get_title()
+        if not title:
             self.logger.error(
-                "Site is asking for a Verification Token. You may need to whitelist your IP!",
+                "Cannot read page title after login - you may have the wrong 'wait until' strategy configured!",
             )
             return False
-        if "Login" in self.browser.title:
-            self.logger.error(
-                "Authentication failed. You may have given the wrong password!",
-            )
+
+
+        if "Verify" in title:
+            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!")
             return False
 
         self.logged_in = True
@@ -665,26 +901,32 @@ class BrowserAutomation:
 
     # end method definition
 
-    def implicit_wait(self, wait_time: float) -> None:
+    def set_timeout(self, wait_time: float) -> None:
         """Wait for the browser to finish tasks (e.g. fully loading a page).
 
         This setting is valid for the whole browser session and not just
         for a single command.
 
         Args:
-            wait_time (float): time in seconds to wait
+            wait_time (float):
+                The time in seconds to wait.
 
         """
 
-        self.logger.debug("Implicit wait for max -> %s seconds...", str(wait_time))
-        self.browser.implicitly_wait(wait_time)
+        self.logger.debug("Setting default timeout to -> %s seconds...", str(wait_time))
+        self.page.set_default_timeout(wait_time * 1000)
+        self.logger.debug("Setting navigation timeout to -> %s seconds...", str(wait_time))
+        self.page.set_default_navigation_timeout(wait_time * 1000)
 
     # end method definition
 
     def end_session(self) -> None:
-        """End the browser session. This is just like closing a tab not ending the browser."""
+        """End the browser session and close the browser."""
 
+        self.logger.debug("Ending browser automation session...")
+        self.context.close()
         self.browser.close()
         self.logged_in = False
+        self.playwright.stop()
 
     # end method definition