robotframework-lynqa 0.1.0__py3-none-any.whl

robotframework_lynqa/__init__.py

@@ -0,0 +1,5 @@
+"""Robot Framework library for executing Lynqa test runs."""
+
+from robotframework_lynqa.library import BASE_URL, LynqaLibrary
+
+__all__ = ["BASE_URL", "LynqaLibrary"]

robotframework_lynqa/atest/lynqa_search.robot

@@ -0,0 +1,19 @@
+*** Settings ***
+Documentation       Acceptance test executed against the real Lynqa service.
+...                 Requires the ``LYNQA_API_KEY`` environment variable to be set to a valid Lynqa API key.
+...                 Runs a Google search for "lynqa" and checks that the first result mentions "Smartesting".
+
+Library             robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+
+*** Variables ***
+${LYNQA_URL}    https://www.google.com/
+
+
+*** Test Cases ***
+Search Engine
+    Given    go to the website
+    When    I look at the search input
+    Then    the search input exists
+    When    I search for 'lynqa'
+    Then    several results are displayed and the first results display 'Smartesting'

robotframework_lynqa/library.py

@@ -0,0 +1,338 @@
+"""Robot Framework test library and listener for the Lynqa execution agent.
+
+This module exposes :class:`LynqaLibrary`, a Robot Framework library that lets you write scenarios in plain Gherkin and
+have them executed by the Lynqa AI agent instead of by locally defined keywords.
+
+Scenarios are written with the ``Given``/``When``/``Then`` keywords, each taking a single natural-language step as its
+argument:
+
+::
+
+    *** Settings ***
+    Library    robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+    *** Variables ***
+    ${LYNQA_URL}    https://example.com/
+
+    *** Test Cases ***
+    Search For An Item
+        Given    the home page is open
+        When     the user searches for an item
+        Then     matching results are displayed
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Any
+
+import pylynqa
+from pylynqa import LynqaClient, TestData, TestRunContext
+from robot.api import SuiteVisitor, logger
+from robot.api.deco import keyword
+from robot.libraries.BuiltIn import BuiltIn
+
+from robotframework_lynqa.reporter import StepReporter
+
+BASE_URL = "https://api.lynqa.smartesting.com"
+
+GHERKIN_KEYWORDS = ("Given", "When", "Then")
+
+# Statuses that mean the run is not finished yet.
+PENDING_STATUSES = ("waiting", "running", "not_run")
+
+# How often to poll the run status, and how long to wait before giving up.
+POLL_INTERVAL_SECONDS = 10
+RUN_TIMEOUT_SECONDS = 3600
+
+# Variable names
+URL_VAR = "${LYNQA_URL}"
+LANGUAGE_VAR = "${LYNQA_LANGUAGE}"
+DATETIME_VAR = "${LYNQA_DATETIME}"
+SECRETS_VAR = "&{LYNQA_SECRETS}"
+
+
+class _GherkinStepCollector(SuiteVisitor):
+    """Collect the Gherkin steps of a running test case.
+
+    Walks a Robot Framework test case and records every keyword call whose name is one of :data:`GHERKIN_KEYWORDS`,
+    rebuilding the original Gherkin step (keyword name followed by its argument text).
+    """
+
+    def __init__(self) -> None:
+        """Initialize the collector with an empty list of steps."""
+        self.steps: list[str] = []
+
+    def start_keyword(self, keyword) -> None:
+        """Record the keyword when it is one of the Gherkin step keywords.
+
+        :param keyword: Running keyword visited by Robot Framework.
+        """
+        if keyword.name in GHERKIN_KEYWORDS:
+            text_step = ""
+            if len(keyword.args) > 0:
+                text_step = keyword.args[0]
+            self.steps.append(f"{keyword.name} {text_step}")
+
+
+class LynqaLibrary:
+    """Robot Framework library that runs Gherkin scenarios via Lynqa.
+
+    Acts both as a test library exposing the Gherkin step keywords (``Given``/``When``/``Then``) and as a listener that
+    captures each scenario and submits it to the Lynqa execution agent.
+
+    **Execution timeout**:
+
+        Once a scenario is submitted, the library polls Lynqa until the run reaches a final status, waiting up to **1
+        hour** before failing the test with a timeout error. To change this behaviour, use Robot Framework's timeout
+        feature (the ``Test Timeout`` suite setting or a ``[Timeout]`` on the test case), which caps how long a test is
+        allowed to run.
+    """
+
+    ROBOT_LIBRARY_SCOPE = "TEST"
+    ROBOT_LIBRARY_DOC_FORMAT = "reST"
+    ROBOT_AUTO_KEYWORDS = False
+
+    def __init__(self, api_key: str, base_url: str = BASE_URL) -> None:
+        """Initialize the Lynqa library.
+
+        :param api_key: API key used to authenticate against the Lynqa service.
+        :param base_url: Base URL of the Lynqa API.
+        """
+        self.ROBOT_LIBRARY_LISTENER = self
+        self._init_client(api_key, base_url)
+        self._run_id: str = ""
+        self._start_error: Exception | None = None
+        self._step_index: int = 0
+        self._reporter: StepReporter | None = None
+
+        self.scenario: str = ""
+        self.url: str | None = ""
+        self.context: TestRunContext = TestRunContext()
+        self.results: dict[str, Any] = {}
+
+    def _init_client(self, api_key: str, base_url: str):
+        """Initialize the Lynqa client.
+
+        :param api_key: API key used to authenticate against the Lynqa service.
+        :param base_url: Base URL of the Lynqa API.
+        """
+        pylynqa.client._PACKAGE_CONSUMER_NAME = "petit-robot:robotframework-lynqa"  # ty: ignore[invalid-assignment]   # ruff: ignore[private-member-access]
+        self._client = LynqaClient(api_key=api_key, base_url=base_url)
+
+    # ------------------------------------------------------------------
+    # Listener interface
+    # ------------------------------------------------------------------
+
+    def start_test(self, data, result) -> None:
+        """Collect the scenario's Gherkin steps when a test starts.
+
+        Reads the running test case with a :class:`_GherkinStepCollector` visitor and stores its
+        ``Given``/``When``/``Then`` steps as the current scenario.
+
+        Any exception raised while preparing the run is captured and turned into a test failure in :meth:`end_test` (a
+        status set here would otherwise be overwritten when the test body runs).
+
+        :param data: Running test case provided by Robot Framework.
+        :param result: Test result object provided by Robot Framework.
+        """
+
+        def collect_steps(data):
+            """Collect the Gherkin steps from the running test case."""
+            collector = _GherkinStepCollector()
+            data.visit(collector)
+            return collector.steps
+
+        self._start_error = None
+        self._step_index = 0
+        try:
+            self.scenario = "\n".join(collect_steps(data))
+            url = self._search_variable(URL_VAR)
+            self.url = None if url is None else str(url)
+            self.context = self._search_context()
+            self._execute_lynqa_testrun(name=data.name)
+        except Exception as error:
+            logger.error(f"Lynqa run preparation failed: {error}")
+            self._start_error = error
+
+    def end_test(self, data, result) -> None:
+        """Fail the current test if :meth:`start_test` caught an exception.
+
+        :param data: Running test case provided by Robot Framework.
+        :param result: Test result object provided by Robot Framework.
+        """
+        if self._start_error is not None:
+            result.status = "FAIL"
+            result.message = f"Lynqa execution failed: {self._start_error}"
+            return
+
+        self._report_test_results(result)
+
+    def start_keyword(self, data, result) -> None:
+        """Log the commands and assertions of a Gherkin keyword's Lynqa step.
+
+        Logging happens here, when the keyword starts, rather than in the keyword body: Robot Framework stops executing
+        the bodies of the keywords that follow a failed one, but :meth:`start_keyword` still fires for them, so every
+        Gherkin keyword gets its logs. The step is matched in execution order via :attr:`_step_index`, which is only
+        incremented later in :meth:`end_keyword`.
+
+        :param data: Running keyword provided by Robot Framework.
+        :param result: Keyword result object provided by Robot Framework.
+        """
+        if data.name not in GHERKIN_KEYWORDS:
+            return
+        if self._reporter is not None:
+            self._reporter.log_step(self._step_index, self.results)
+
+    def end_keyword(self, data, result) -> None:
+        """Set each Gherkin keyword's status from its matching Lynqa step.
+
+        Only the Gherkin step keywords are reported; other keywords (logging, setup, ...) keep the status Robot
+        Framework gave them.
+
+        :param data: Running keyword provided by Robot Framework.
+        :param result: Keyword result object provided by Robot Framework.
+        """
+        if data.name not in GHERKIN_KEYWORDS:
+            return
+        steps = self.results.get("stepStatuses", [])
+        if self._step_index < len(steps):
+            step_status = steps[self._step_index].get("status")
+        else:
+            # No per-step detail: fall back to the overall run status.
+            step_status = self.results.get("status")
+        result.status = "PASS" if step_status == "success" else "FAIL"
+        self._step_index += 1
+
+    def _execute_lynqa_testrun(self, name: str, timeout: float = RUN_TIMEOUT_SECONDS):
+        """Start a Lynqa test run and wait for it to reach a final status.
+
+        Polls the run status every :data:`POLL_INTERVAL_SECONDS` seconds until it leaves the :data:`PENDING_STATUSES`,
+        giving up after ``timeout`` seconds so the run cannot hang forever when a final status is never reached.
+
+        :param name: Name of the test run.
+        :param timeout: Maximum time, in seconds, to wait for the run to finish.
+
+        :raises TimeoutError: If the run is still pending once ``timeout`` elapses.
+        """
+        if not self.url:
+            raise ValueError(f"No URL configured. Please set the {URL_VAR} variable.")  # ruff: ignore[raise-vanilla-args]
+
+        self._run_id = self._client.add_gherkin_test_run(
+            url=self.url,
+            name=name,
+            scenario=self.scenario,
+        )
+        logger.info(f"Testrun ID is: {self._run_id}")
+        self._wait_until_testrun_end(timeout)
+        self.results = self._client.get_test_run_full_status(self._run_id)
+        self._reporter = StepReporter(self._client, self._run_id, self.url)
+
+    def _wait_until_testrun_end(self, timeout: float):
+        """Wait until the test run reaches a final status.
+
+        Polls the run status every :data:`POLL_INTERVAL_SECONDS` seconds until it leaves the :data:`PENDING_STATUSES`.
+
+        :param timeout: Maximum time, in seconds, to wait for the run to finish.
+
+        :raises TimeoutError: If the run is still pending once ``timeout`` elapses.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            status = self._client.get_test_run_status(self._run_id).get("status")
+            logger.debug(f"Current run status: {status}")
+            if status not in PENDING_STATUSES:
+                return
+            if time.monotonic() >= deadline:
+                msg = f"Lynqa test run {self._run_id} did not complete within {timeout}s"
+                raise TimeoutError(msg)
+            time.sleep(POLL_INTERVAL_SECONDS)
+
+    def _report_test_results(self, result):
+        """Report the test results from the Lynqa API.
+
+        Sets the test status to ``PASS`` when the run succeeded and ``FAIL`` otherwise, and copies the run's status
+        message onto the result.
+
+        :param result: Test result object provided by Robot Framework.
+        """
+        if self.results.get("status") == "success":
+            result.status = "PASS"
+        else:
+            result.status = "FAIL"
+
+        result.message = self.results.get("statusMessage")
+
+    # ------------------------------------------------------------------
+    # Keywords exposed to Robot Framework
+    # ------------------------------------------------------------------
+
+    @keyword
+    def given(self, text: str) -> None:
+        """Create a ``Given`` step in the current scenario.
+
+        :param text: Natural-language description of the step.
+        """
+
+    @keyword
+    def when(self, text: str) -> None:
+        """Create a ``When`` step in the current scenario.
+
+        :param text: Natural-language description of the step.
+        """
+
+    @keyword
+    def then(self, text: str) -> None:
+        """Create a ``Then`` step in the current scenario.
+
+        :param text: Natural-language description of the step.
+        """
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _search_variable(variable_name) -> object:
+        """Return the value of a Robot Framework variable.
+
+        :param variable_name: Name of the variable to look up, e.g. ``${LYNQA_URL}``.
+
+        :returns: The variable's value, or ``None`` when it is not set.
+        """
+        return BuiltIn().get_variable_value(variable_name)
+
+    def _search_secrets_variables(self) -> list[TestData]:
+        """Convert the secrets variable into a list of :class:`TestData`.
+
+        The ``&{LYNQA_SECRETS}`` variable is expected to be a mapping of secret name to value, e.g. ``login=superu
+        password=TrèsS3cr3t``. Each entry is turned into a :class:`TestData` name/value pair.
+
+        :returns: The secrets as :class:`TestData` items, or an empty list if unset.
+
+        :raises TypeError: If the secrets variable is not a name/value mapping.
+        """
+        raw_secrets = self._search_variable(SECRETS_VAR)
+        if not raw_secrets:
+            return []
+        if not isinstance(raw_secrets, dict):
+            raise TypeError("Invalid secrets variable, expected a dict")  # ruff: ignore[raise-vanilla-args]
+        return [TestData(name=str(name), value=str(value)) for name, value in raw_secrets.items()]
+
+    def _search_context(self) -> TestRunContext:
+        """Build the Lynqa run context from the ``LYNQA_*`` Robot Framework variables.
+
+        Reads the optional ``${LYNQA_LANGUAGE}`` and ``${LYNQA_DATETIME}`` variables and the ``&{LYNQA_SECRETS}``
+        mapping. When ``${LYNQA_DATETIME}`` is not set, the current local date and time is used.
+
+        :returns: The context passed to the Lynqa test run.
+        """
+        client_language = self._search_variable(LANGUAGE_VAR)
+        client_datetime = self._search_variable(DATETIME_VAR)
+        if client_datetime is None:
+            client_datetime = datetime.now().astimezone().strftime("%a %b %d %Y %H:%M:%S GMT%z")
+        secrets = self._search_secrets_variables()
+        return TestRunContext(
+            client_language=str(client_language), client_datetime=str(client_datetime), secrets=secrets
+        )

robotframework_lynqa/reporter.py

@@ -0,0 +1,150 @@
+"""Robot Framework log presentation for Lynqa test runs."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from robot.api import logger
+
+if TYPE_CHECKING:
+    from pylynqa import LynqaClient
+
+
+class StepReporter:
+    """Render the Robot log for one Lynqa test run step.
+
+    Holds the run data needed to embed screenshots and caption commands and assertions, and exposes :meth:`log_step` to
+    log a single step's details under the current keyword.
+    """
+
+    def __init__(self, client: LynqaClient, run_id: str, url: str | None) -> None:
+        """Initialize the reporter for a single run.
+
+        :param client: Lynqa client used to fetch screenshots.
+        :param run_id: Identifier of the Lynqa test run.
+        :param url: URL the run was started against, shown with the initial screenshot.
+        """
+        self._client = client
+        self._run_id = run_id
+        self._url = url
+
+    def log_step(self, step_index: int, results: dict) -> None:
+        """Log the commands and assertions of a Gherkin step.
+
+        Logs a ``Command`` list with one log per command and an ``Assertion`` list with one log per assertion, each
+        followed by its screenshots if any. The initial screenshot captured before the run is embedded once, ahead of
+        the first step's commands. The step is the one at ``step_index`` in the run's ``stepStatuses``.
+
+        :param step_index: Index of the step to log, in execution order.
+        :param results: Full status of the run, as returned by the Lynqa API.
+        """
+        steps = results.get("stepStatuses", [])
+        if step_index >= len(steps):
+            return
+        step = steps[step_index]
+
+        if step_index == 0:
+            self._log_initial_report(results)
+        self._log_step_commands(step)
+        self._log_step_assertions(step)
+
+    def _log_initial_report(self, results) -> None:
+        """Log the initial report (global info).
+
+        :param results: Full status of the run, as returned by the Lynqa API.
+        """
+        initial_report = results.get("initialReport", {})
+        logger.info(self._embed_screenshot(initial_report.get("screenshot"), f"Open URL {self._url}"), html=True)
+
+    def _log_step_commands(self, step: dict) -> None:
+        """Log the current step's commands and embed their screenshots.
+
+        :param step: The step from the run's ``stepStatuses`` to log.
+        """
+
+        def _is_response_success(command):
+            return "success" in command.get("response", {})
+
+        for command in step.get("commands", []):
+            level = "INFO" if _is_response_success(command) else "ERROR"
+            logger.write(
+                self._embed_screenshot(command.get("screenshot"), self._command_caption(command)),
+                level=level,
+                html=True,
+            )
+
+    @staticmethod
+    def _command_caption(command: dict) -> str:
+        """Build a human-readable caption for a command's screenshot.
+
+        :param command: A command entry from a step's ``commands`` list.
+
+        :returns: The command name enriched with available information.
+        """
+        caption = f"Command: {command.get('name', '')}"
+        if "value" in command:
+            caption += f"(value: {command['value']})"
+        elif "button" in command:
+            caption += f"(button: {command['button']})"
+        if command.get("htmlElement"):
+            caption += f' on element "{command["htmlElement"]}"'
+        return str(caption)
+
+    def _log_step_assertions(self, step: dict) -> None:
+        """Log the current step's assertions and embed the assertions report screenshot.
+
+        :param step: The step from the run's ``stepStatuses`` to log.
+        """
+
+        def _is_assertion_checked(assertion):
+            return assertion.get("checked", False)
+
+        report = step.get("assertionsReport", {})
+        assertions = report.get("assertions", [])
+
+        for assertion in assertions:
+            level = "INFO" if _is_assertion_checked(assertion) else "ERROR"
+            logger.write(
+                self._assertion_caption(assertion),
+                level=level,
+                html=True,
+            )
+        if "testVerdictCause" in step:
+            logger.error(f"Verdict: {step['testVerdictCause']}")
+
+        logger.info(self._embed_screenshot(report.get("screenshot"), ""), html=True)
+
+    @staticmethod
+    def _assertion_caption(assertion):
+        """Build a human-readable caption for an assertion.
+
+        :param assertion: An assertion entry from a step's ``assertionsReport`` assertions list.
+
+        :returns: The assertion text enriched with available information.
+        """
+        caption = f'Assertion: "{assertion.get("assertion", "")}"'
+        return str(caption)
+
+    def _embed_screenshot(self, screenshot_id: str | None, caption: str) -> str:
+        """Fetch a Lynqa screenshot and return it embedded inline in an HTML string.
+
+        Downloads the screenshot as base64-encoded PNG data and wraps it in an ``<img>`` inside a collapsible
+        ``<details>`` block. A download failure is logged and caught, so it never fails the test run.
+
+        :param screenshot_id: UUID of the screenshot to fetch, or ``None`` when the step has none.
+        :param caption: Text shown above the embedded image.
+
+        :returns: The caption and embedded image as an HTML string, or an empty string when there is no screenshot or
+            the download failed.
+        """
+        if not screenshot_id:
+            return ""
+        try:
+            data = self._client.get_screenshot(self._run_id, screenshot_id)
+        except Exception as error:
+            logger.error(f"Failed to fetch Lynqa screenshot {screenshot_id}: {error}")
+            return ""
+        return (
+            f'{caption}<details><summary>screenshot</summary><img src="data:image/png;base64,{data}"'
+            + 'style="max-width: 100%;"/></details>'
+        )

robotframework_lynqa/test/__init__.py

@@ -0,0 +1,28 @@
+"""Unit tests for robotframework_lynqa."""
+
+from robot.api.interfaces import ListenerV3
+
+# ruff: file-ignore[non-empty-init-module]
+from robot.libraries.BuiltIn import BuiltIn
+
+API_KEY = "fake_api_key"
+
+
+class _CaptureLibInstance(ListenerV3):
+    """Listener that captures the live LynqaLibrary instance during the run.
+
+    The ``.robot`` file owns the :class:`LynqaLibrary` instance (it is created by the ``Library`` import), so the test
+    cannot reference it directly. This listener grabs that instance from the running context before the test ends.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the capture listener."""
+        self.instance = None
+
+    def end_test(self, data, result) -> None:
+        """Capture the library instance while the execution context is alive.
+
+        :param data: Running test data passed by Robot Framework.
+        :param result: Test result object passed by Robot Framework.
+        """
+        self.instance = BuiltIn().get_library_instance("robotframework_lynqa.LynqaLibrary")

robotframework_lynqa/test/conftest.py

@@ -0,0 +1,29 @@
+"""Pytest configuration for tests."""
+
+import base64
+from pathlib import Path
+
+import pytest
+from pylynqa.models import TestData, TestRunContext
+
+SCREENSHOT_PNG_FILE = Path(__file__).parent / "data_set" / "screenshot.png"
+
+
+def pytest_configure(config):
+    """Pytest configuration tests."""
+    # Prevent pytest from collecting these model classes as test suites
+    # (their names start with "Test" but they are domain objects, not test cases).
+    TestData.__test__ = False  # ty: ignore[unresolved-attribute]
+    TestRunContext.__test__ = False  # ty: ignore[unresolved-attribute]
+
+
+@pytest.fixture
+def screenshot_base64():
+    """Return the sample screenshot as base64-encoded PNG data.
+
+    Shared by the library integration tests and the reporter unit tests as the fake payload returned by the mocked
+    ``get_screenshot`` client call.
+
+    :returns: Base64-encoded contents of the sample PNG fixture.
+    """
+    return base64.b64encode(SCREENSHOT_PNG_FILE.read_bytes()).decode()

robotframework_lynqa/test/data_set/test_lynqa_nominal.robot

@@ -0,0 +1,17 @@
+*** Settings ***
+Library     robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+
+*** Variables ***
+${LYNQA_URL}            https://www.super-u.ai
+${LYNQA_LANGUAGE}       rf-RF
+&{LYNQA_SECRETS}        login=superu    password=TrèsS3cr3t
+
+
+*** Test Cases ***
+Browsing And Buying An AI Agent
+    Given    the storefront is open at the home page
+    When    the user searches for an autonomous testing agent
+    When    the user filters the results to top-rated agents under 50 credits
+    Then    a list of matching AI agents is displayed with their prices
+    Then    the premium "Bobcat" agent is sold out because its success

robotframework_lynqa/test/data_set/test_lynqa_with_date.robot

@@ -0,0 +1,17 @@
+*** Settings ***
+Library     DateTime
+Library     robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+
+*** Variables ***
+${LYNQA_URL}            https://www.super-u.ai
+${LYNQA_LANGUAGE}       rf-RF
+${LYNQA_DATETIME}       Wed May 8 2026 09:00:00 GMT+0200
+&{LYNQA_SECRETS}        login=superu    password=TrèsS3cr3t
+
+
+*** Test Cases ***
+Browsing And Buying An AI Agent With Date
+    Given    the storefront is open at the home page
+    When    the user searches for an autonomous testing agent
+    Then    a list of matching AI agents is displayed with their prices

robotframework_lynqa/test/data_set/test_lynqa_with_results.robot

@@ -0,0 +1,15 @@
+*** Settings ***
+Library     robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+
+*** Variables ***
+${LYNQA_URL}    https://www.google.com/
+
+
+*** Test Cases ***
+Search Engine
+    Given    go to the website
+    When    I look at the search input
+    Then    the search input exists
+    When    I search for 'lynqa'
+    Then    several results are displayed and the first results display 'Smartesting'

robotframework_lynqa/test/data_set/test_lynqa_without_url.robot

@@ -0,0 +1,16 @@
+*** Settings ***
+Library     DateTime
+Library     robotframework_lynqa.LynqaLibrary    api_key=%{LYNQA_API_KEY}
+
+
+*** Variables ***
+${LYNQA_LANGUAGE}       rf-RF
+${LYNQA_DATETIME}       Wed May 8 2026 09:00:00 GMT+0200
+&{LYNQA_SECRETS}        login=superu    password=TrèsS3cr3t
+
+
+*** Test Cases ***
+Browsing And Buying An AI Agent Without URL
+    Given    the storefront is open at the home page
+    When    the user searches for an autonomous testing agent
+    Then    a list of matching AI agents is displayed with their prices