feat: creating test that prove new Python usage documentation

These new test proves and documents library usage when libary is extended from Python. Use to verify documentation to be written in robotframework-browser.org

Author: aaltat

atest/README.md

@@ -6,10 +6,14 @@ Robot Framework acceptance tests for the Browser library.
 
 ```
 atest/
-├── test/               # Test suites (00–12 numbered by feature area)
-│   └── __init__.robot  # Suite setup/teardown + global library imports
+├── test/               # Test suites (00–13 numbered by feature area)
+│   ├── __init__.robot  # Suite setup/teardown + global library imports
+│   └── 13_Python_Extension/  # Demonstrates using Browser from a user's own Python library.
+│       └── _child/     # Suites run as child processes. Robot Framework skips "_" directories
+│                       # when walking, so these do not run in the normal suite collection.
 ├── library/            # Python helper libraries
 │   ├── common.py       # Test server lifecycle (start/stop, log capture)
+│   ├── child_result.py # Assertions about a child robot run's output.xml and playwright-log
 │   └── test_app_listener.py  # RF listener → test-app /api/log/context
 └── output/             # Generated by test runs (gitignored)
     └── test-app/       # Per-process newline-delimited JSON logs

atest/library/child_result.py

@@ -0,0 +1,139 @@
+"""Assertions about what a child Robot Framework run did.
+
+Used by atest/test/13_Python_Extension/python_extension.robot, which starts
+child `robot` runs and then verifies their results. This lives here rather than
+next to those suites on purpose: the files under 13_Python_Extension/ are
+quoted by path in the documentation on robotframework-browser.org and must stay
+free of test scaffolding.
+"""
+
+import json
+import re
+from pathlib import Path
+
+from robot.api import logger
+from robot.result import ExecutionResult, Result, TestCase
+
+
+def get_child_result(output_xml: Path) -> Result:
+    """Parse the output.xml of a child run."""
+    result = ExecutionResult(str(output_xml))
+    logger.info(f"Parsed {output_xml}")
+    return result
+
+
+def child_test_status_should_be(
+    result: Result,
+    name: str,
+    status: str,
+    message_pattern: str | None = None,
+):
+    """Verify status, and optionally the failure message, of a child run test."""
+    test = _get_test(result, name)
+    assert test.status == status, (
+        f"Test '{name}' status was '{test.status}', expected '{status}'. "
+        f"Message: {test.message}"
+    )
+    if message_pattern is not None:
+        assert re.search(message_pattern, test.message), (
+            f"Test '{name}' message '{test.message}' does not match '{message_pattern}'"
+        )
+
+
+def child_keyword_should_log(
+    result: Result,
+    test_name: str,
+    owner: str,
+    message_pattern: str,
+):
+    """Verify a message was logged inside a keyword owned by the given library.
+
+    Browser keywords called from Python do not appear in output.xml as keywords
+    of their own, but everything they log lands inside the keyword of the
+    library that called them.
+    """
+    messages = []
+    for keyword in _get_keywords(_get_test(result, test_name)):
+        if keyword.owner != owner:
+            continue
+        for message in keyword.messages:
+            messages.append(message.message)
+            if re.search(message_pattern, message.message):
+                logger.info(
+                    f"Found '{message_pattern}' in keyword "
+                    f"'{keyword.full_name}': {message.message}"
+                )
+                return
+    raise AssertionError(
+        f"No message matching '{message_pattern}' logged by a '{owner}' keyword "
+        f"in test '{test_name}'. Messages: {messages}"
+    )
+
+
+def child_should_not_use_library(result: Result, library: str):
+    """Verify the child run did not call any keyword of the given library.
+
+    Guards context B: if a child suite ever imports Browser as a Robot
+    Framework library, the listener registers and the context collapses into
+    context A without any test failing.
+    """
+    for test in result.suite.tests:
+        for keyword in _get_keywords(test):
+            assert keyword.owner != library, (
+                f"Test '{test.name}' called '{keyword.full_name}' "
+                f"from library '{library}'"
+            )
+
+
+def playwright_log_should_have_rf_context(log_file: Path, expected: str):
+    """Verify node side log records carry the Robot Framework test name."""
+    test_names = _logged_test_names(log_file)
+    assert any(expected in name for name in test_names), (
+        f"No node side log record with test name containing '{expected}'. "
+        f"Found: {sorted(test_names)}"
+    )
+
+
+def playwright_log_should_not_have_rf_context(log_file: Path):
+    """Verify node side log records carry no Robot Framework test name."""
+    test_names = _logged_test_names(log_file)
+    assert not test_names, (
+        f"Node side log records unexpectedly carry test names: {sorted(test_names)}"
+    )
+
+
+def _logged_test_names(log_file: Path) -> set:
+    log_file = Path(log_file)
+    assert log_file.is_file(), (
+        f"{log_file} not found. The child run did not start its own node process."
+    )
+    test_names = set()
+    for raw_line in log_file.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = raw_line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(record, dict) and record.get("test_name"):
+            test_names.add(record["test_name"])
+    logger.info(f"Test names in {log_file}: {sorted(test_names)}")
+    return test_names
+
+
+def _get_test(result: Result, name: str) -> TestCase:
+    for test in result.suite.tests:
+        if test.name == name:
+            return test
+    names = [test.name for test in result.suite.tests]
+    raise AssertionError(f"Test '{name}' not found from child run. Found: {names}")
+
+
+def _get_keywords(item) -> list:
+    keywords = []
+    for child in item.body:
+        if child.type == child.KEYWORD:
+            keywords.append(child)
+            keywords.extend(_get_keywords(child))
+    return keywords

atest/library/os_wrapper.py

@@ -67,6 +67,35 @@ def get_enty_command() -> str:
     return f"{sys.executable} -m Browser.entry"
 
 
+def get_robot_command() -> str:
+    """Return the command that starts a child Robot Framework run."""
+    return f"{sys.executable} -m robot"
+
+
+def get_child_robot_environment() -> dict:
+    """Return the environment for a child robot run that starts its own node process.
+
+    `inv atest` starts one shared node process for the whole run and exports
+    ROBOT_FRAMEWORK_BROWSER_NODE_PORT and DEBUG for it (tasks.py). A child run
+    that inherited those would connect to the shared process instead of
+    starting its own and would never write its own playwright-log.txt.
+    The pino log level is set rather than inherited so the child behaves the
+    same under `inv atest` and `inv atest-robot`.
+    """
+    env = os.environ.copy()
+    env.pop("ROBOT_FRAMEWORK_BROWSER_NODE_PORT", None)
+    env.pop("DEBUG", None)
+    env["ROBOT_FRAMEWORK_BROWSER_PINO_LOG_LEVEL"] = "debug"
+    return env
+
+
+def count_files(path: str, pattern: str) -> int:
+    """Return count of files matching pattern, also when path does not exist."""
+    files = sorted(str(file) for file in Path(path).glob(pattern))
+    logger.info(f'Files matching "{pattern}" in "{path}": {files}')
+    return len(files)
+
+
 def verify_translation(filename: Path) -> dict:
     """Verifies translation file."""
     with filename.open("r") as file:

atest/test/13_Python_Extension/__init__.robot

@@ -0,0 +1,5 @@
+*** Settings ***
+Documentation       Every test here starts a child `robot` run, which starts its own node process
+...                 and browser. That does not fit the 30 second default test timeout.
+
+Test Timeout        3 minutes

atest/test/13_Python_Extension/_child/MyLibraryA.py

@@ -0,0 +1,101 @@
+"""Context A: Robot Framework imports Browser, this library sits alongside it.
+
+Demonstration library for the Browser documentation. It is quoted by path on
+robotframework-browser.org, so it deliberately contains no business logic and
+nothing that is not part of the example.
+
+See MyLibraryB.py for context B, where the library owns the Browser instance.
+"""
+
+import functools
+
+from robot.libraries.BuiltIn import BuiltIn
+
+from Browser import Browser
+
+
+def screenshot_on_failure(keyword):
+    """Take a screenshot when the wrapped keyword fails, then re-raise.
+
+    Browser runs its own ``run_on_failure`` from the Robot Framework dynamic
+    library API, which is not entered when a keyword is called from Python.
+    A small library can get equivalent behaviour with a decorator like this.
+    Larger libraries usually intercept in one place instead, either by being a
+    dynamic library themselves or by using PythonLibCore.
+    """
+
+    @functools.wraps(keyword)
+    def wrapper(self, *args, **kwargs):
+        try:
+            return keyword(self, *args, **kwargs)
+        except Exception:
+            self.browser.take_screenshot("my-library-failure-{index}")
+            raise
+
+    return wrapper
+
+
+class MyLibraryA:
+    """Business logic in Python, with Browser still owned by Robot Framework."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def __init__(self):
+        self._browser: Browser | None = None
+
+    @property
+    def browser(self) -> Browser:
+        """The Browser instance that Robot Framework imported.
+
+        Looked up on first use rather than in ``__init__``, because Robot
+        Framework may not have imported Browser yet when this library is
+        constructed.
+        """
+        if self._browser is None:
+            self._browser = BuiltIn().get_library_instance("Browser")
+        return self._browser
+
+    def open_login_page(self, url: str):
+        self.browser.new_browser(headless=True)
+        self.browser.new_page(url)
+
+    def click_heading_with_middle_mouse_button(self):
+        """Call Browser with plain Python values.
+
+        ``"middle"`` becomes a ``MouseButton``, ``"2 seconds"`` becomes a
+        ``timedelta``, and the ``None`` stays ``None`` instead of turning into
+        the string ``"None"``.
+        """
+        self.browser.wait_for_elements_state("id=heading1", "visible", "2 seconds")
+        self.browser.click("id=heading1", "middle")
+        return self.browser.evaluate_javascript(None, "() => 'evaluated'")
+
+    def get_browser_output_directory(self) -> str:
+        return self.browser.outputdir
+
+    def get_heading_with_validate_and_then(self) -> list:
+        validated = self.browser.get_text(
+            "id=heading1", "validate", "value == 'Login Page'"
+        )
+        transformed = self.browser.get_text("id=heading1", "then", "value.upper()")
+        return [validated, transformed]
+
+    def set_test_scoped_browser_timeout(self, timeout: str) -> str:
+        return self.browser.set_browser_timeout(timeout, "Test")
+
+    def set_browser_timeout_and_return_previous(self, timeout: str) -> str:
+        return self.browser.set_browser_timeout(timeout)
+
+    def get_open_page_count(self) -> int:
+        return sum(
+            len(context["pages"])
+            for browser in self.browser.get_browser_catalog()
+            for context in browser["contexts"]
+        )
+
+    def click_missing_element(self):
+        self.browser.click("id=this_element_does_not_exist")
+
+    @screenshot_on_failure
+    def click_missing_element_with_screenshot(self):
+        self.browser.click("id=this_element_does_not_exist")

atest/test/13_Python_Extension/_child/MyLibraryB.py

@@ -0,0 +1,72 @@
+"""Context B: Robot Framework imports only this library, which owns Browser.
+
+Demonstration library for the Browser documentation. It is quoted by path on
+robotframework-browser.org, so it deliberately contains no business logic and
+nothing that is not part of the example.
+
+MyLibraryB_no_listener.py is the same library without the listener
+registration, and the difference between the two is what the registration buys.
+"""
+
+from Browser import Browser
+
+
+class MyLibraryB:
+    """Browser used as a base, with this library owning the instance."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+    # Robot Framework resolves the listener API version of every listener
+    # separately. Browser declares version 2, but this library would default to
+    # version 3, which has different method signatures.
+    ROBOT_LISTENER_API_VERSION = 2
+
+    def __init__(self):
+        self._browser = Browser(enable_playwright_debug=True)
+        # Robot Framework accepts a list of listeners and calls Browser's
+        # listener methods itself. Without this line Browser gets no suite and
+        # test events, so automatic closing and scope settings do not work.
+        self.ROBOT_LIBRARY_LISTENER = [self, self._browser]
+
+    def open_login_page(self, url: str):
+        self._browser.new_browser(headless=True)
+        self._browser.new_page(url)
+
+    def click_heading_with_middle_mouse_button(self):
+        """Call Browser with plain Python values.
+
+        ``"middle"`` becomes a ``MouseButton``, ``"2 seconds"`` becomes a
+        ``timedelta``, and the ``None`` stays ``None`` instead of turning into
+        the string ``"None"``.
+        """
+        self._browser.wait_for_elements_state("id=heading1", "visible", "2 seconds")
+        self._browser.click("id=heading1", "middle")
+        return self._browser.evaluate_javascript(None, "() => 'evaluated'")
+
+    def get_browser_output_directory(self) -> str:
+        return self._browser.outputdir
+
+    def get_heading_with_validate_and_then(self) -> list:
+        validated = self._browser.get_text(
+            "id=heading1", "validate", "value == 'Login Page'"
+        )
+        transformed = self._browser.get_text("id=heading1", "then", "value.upper()")
+        return [validated, transformed]
+
+    def set_test_scoped_browser_timeout(self, timeout: str) -> str:
+        return self._browser.set_browser_timeout(timeout, "Test")
+
+    def set_browser_timeout_and_return_previous(self, timeout: str) -> str:
+        return self._browser.set_browser_timeout(timeout)
+
+    def get_open_page_count(self) -> int:
+        return sum(
+            len(context["pages"])
+            for browser in self._browser.get_browser_catalog()
+            for context in browser["contexts"]
+        )
+
+    def click_missing_element(self):
+        self._browser.click("id=this_element_does_not_exist")
+
+    def close_browser_library(self):
+        self._browser.close_browser("ALL")