robotframework-maestrolibrary 0.2.0__py3-none-any.whl

MaestroLibrary/__init__.py

@@ -0,0 +1,231 @@
+import atexit
+import json
+import re
+import shutil
+import subprocess
+import time
+from datetime import timedelta
+
+from robot.api import logger
+from robotlibcore import DynamicCore
+
+from .keywords import ApplicationManagementKeywords, DeviceKeywords, ElementKeywords, KeyeventKeywords, RunOnFailureKeywords, ScreenshotKeywords, TouchKeywords, WaitingKeywords
+from .locators import matches, walk
+from .mcp import MaestroError, MaestroMCP
+
+__version__ = "0.2.0"
+NO_APP = "maestro.no.app"
+SETTLE_TIMEOUT_MS = 3000
+APP_LAUNCH_TIMEOUT_S = 20  # Appium's default appWaitDuration
+ADB_TIMEOUT_S = 10
+MCP_TIMEOUT_S = 300  # how long to wait for one Maestro command flow beyond its own timeouts
+FLOW_TIMEOUT_S = 3600  # a Run Flow file or directory can hold any number of commands
+
+
+class MaestroLibrary(DynamicCore):
+    """MaestroLibrary drives Android and iOS apps through [https://maestro.dev|Maestro].
+
+    It mirrors [https://github.com/serhatbolsu/robotframework-appiumlibrary|AppiumLibrary]:
+    the keyword names, the argument order and the `strategy=value` locators are the same,
+    so most AppiumLibrary suites read the same with this library. There's no Appium server
+    and no capabilities, and Maestro waits for the UI to settle after every action.
+
+    = Locating elements =
+
+    | *Strategy*         | *Example*                  | *Matches*                                              |
+    | text               | ``text=Log in``            | whole text, content-desc or hint, literally            |
+    | accessibility_id   | ``accessibility_id=Back``  | same as text (Maestro matches content-desc as text)    |
+    | id                 | ``id=login_button``        | whole resource-id or Flutter ``Semantics.identifier``  |
+    | regex              | ``regex=Log.*``            | text, as a Maestro (Java) regular expression           |
+    | id_regex           | ``id_regex=.*login``       | id, as a regular expression                            |
+    | point              | ``point=50%,90%``          | a screen position, in percent or pixels                |
+
+    A locator without a strategy is treated as text, because Flutter widgets expose
+    text far more often than ids. xpath, class, android, ios, predicate, chain, css, name and identifier
+    have no Maestro equivalent and fail immediately.
+
+    Actions match on the device with Java regular expressions. The `Should` and `Get`
+    keywords match the inspected screen with Python's ``re``. The two behave the same for
+    literal locators and for common patterns. Keep ``regex=`` and ``id_regex=`` to
+    syntax that both engines share (no possessive quantifiers, ``\\p{...}`` classes or inline flags).
+
+    = Timeouts =
+
+    `timeout` (default 5 seconds) is the default for the `Wait Until` keywords and `Expect`
+    keywords, the same as AppiumLibrary. The `Should` keywords check the current screen once
+    and don't wait. Every action waits for its element on its own.
+
+    = Anything else =
+
+    `Run Flow` runs raw Maestro YAML or a flow file, for the Maestro commands that have
+    no keyword yet.
+    """
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+    ROBOT_LIBRARY_VERSION = __version__
+
+    def __init__(
+        self,
+        timeout: timedelta = timedelta(seconds=5),
+        run_on_failure: str = "Capture Page Screenshot",
+        device: str | None = None,
+        maestro: str = "maestro",
+        speed: timedelta = timedelta(0),
+    ):
+        """`device` is a Maestro device id such as ``emulator-5554``. By default the first
+        connected device is used. `maestro` is the Maestro CLI executable.
+
+        `speed` pauses before every Maestro command, like SeleniumLibrary's speed. Raise it
+        (for example ``speed=0.5s``) when a slow or overloaded emulator stops responding.
+        """
+        self.timeout = timeout
+        self.speed = speed
+        self.run_on_failure_keyword = None if run_on_failure.upper() in ("NOTHING", "NONE", "") else run_on_failure
+        self.device = device
+        self.platform = None
+        self.app_id = None
+        self.mcp = MaestroMCP([maestro, "mcp"])
+        self._running_on_failure = False
+        atexit.register(self.mcp.close)
+        DynamicCore.__init__(self, [
+            ApplicationManagementKeywords(self),
+            ElementKeywords(self),
+            WaitingKeywords(self),
+            TouchKeywords(self),
+            DeviceKeywords(self),
+            KeyeventKeywords(self),
+            ScreenshotKeywords(self),
+            RunOnFailureKeywords(self),
+        ])
+
+    def run_keyword(self, name, args, kwargs=None):
+        try:
+            return DynamicCore.run_keyword(self, name, args, kwargs)
+        except Exception:
+            self.run_on_failure()
+            raise
+
+    def run_on_failure(self):
+        if not self.run_on_failure_keyword or self._running_on_failure:
+            return
+        self._running_on_failure = True
+        try:
+            from robot.libraries.BuiltIn import BuiltIn
+            BuiltIn().run_keyword(self.run_on_failure_keyword)
+        except Exception as err:
+            logger.warn(f"Keyword '{self.run_on_failure_keyword}' could not be run on failure: {err}")
+        finally:
+            self._running_on_failure = False
+
+    def device_id(self):
+        if not self.platform:
+            content = self.mcp.call_tool("list_devices", {})
+            connected = [d for d in json.loads(content[0]["text"])["devices"] if d.get("connected")]
+            if self.device:
+                connected = [d for d in connected if d["device_id"] == self.device]
+            if not connected:
+                raise MaestroError(f"Device '{self.device or 'any'}' is not connected. Start an emulator or "
+                                   "simulator, or connect a device.")
+            self.device, self.platform = connected[0]["device_id"], connected[0]["platform"]
+            logger.info(f"Using {self.platform} device '{self.device}'.")
+        return self.device
+
+    def wait_for_app_focus(self, app_id):
+        """Waits until `app_id` has window focus, like Appium waiting for the app's activity.
+
+        Maestro's launchApp returns while the launch transition is still running, so the
+        first inspect_screen can show the previous app. Android only: other platforms return at once.
+        """
+        self.device_id()
+        if self.platform != "android":
+            return
+        deadline = time.monotonic() + APP_LAUNCH_TIMEOUT_S
+        while time.monotonic() < deadline:
+            focus = self.adb_shell("dumpsys", "window", purpose="waiting for the app's window")
+            if focus is None:
+                return
+            if re.search(rf"mCurrentFocus=.*\s{re.escape(app_id)}/", focus):
+                # Focus arrives before the first frames are drawn; a gesture sent then can be lost.
+                self.run_commands({"waitForAnimationToEnd": {"timeout": SETTLE_TIMEOUT_MS}}, log=False)
+                return
+            # dumpsys window is a heavy call; focus arrived within 2 s in measurements, so 1 s is enough.
+            time.sleep(1)
+        logger.warn(f"App '{app_id}' did not get window focus within {APP_LAUNCH_TIMEOUT_S} s.")
+
+    def adb_shell(self, *args, purpose):
+        """Runs `adb shell args` on the current Android device and returns its output.
+
+        Returns None, with a warning naming `purpose`, when adb is missing or doesn't answer:
+        Maestro itself needs no adb, so the checks built on it degrade instead of failing.
+        """
+        adb = shutil.which("adb")
+        if not adb:
+            logger.warn(f"adb is not on PATH, so {purpose} is skipped. Install Android platform-tools.")
+            return None
+        try:
+            return subprocess.run([adb, "-s", self.device, "shell", *args], capture_output=True,
+                                  text=True, errors="replace", timeout=ADB_TIMEOUT_S).stdout
+        except subprocess.TimeoutExpired:
+            logger.warn(f"adb did not answer within {ADB_TIMEOUT_S} s while {purpose}; is the device responsive?")
+            return None
+
+    def run_commands(self, *commands, app_id=None, log=True):
+        """Runs Maestro commands (dicts or strings) as one flow on the current device."""
+        header = f"appId: {json.dumps(app_id or self.app_id or NO_APP)}\n---\n"
+        body = "\n".join(f"- {json.dumps(command)}" for command in commands)
+        if log:
+            logger.debug(f"Maestro flow:\n{body}")
+        if self.speed:
+            time.sleep(self.speed.total_seconds())
+        # A wait or scroll may legitimately take longer than the default; allow its own timeout.
+        waits = [c[k]["timeout"] for c in commands if isinstance(c, dict) for k in c
+                 if isinstance(c[k], dict) and isinstance(c[k].get("timeout"), int)]
+        self._run({"yaml": header + body}, None, max([MCP_TIMEOUT_S] + [w / 1000 + 60 for w in waits]))
+
+    def run_yaml(self, yaml, env=None):
+        self._run({"yaml": yaml}, env, FLOW_TIMEOUT_S)
+
+    def run_files(self, files, env=None):
+        self._run({"files": files}, env, FLOW_TIMEOUT_S)
+
+    def run_dir(self, path, env=None, include_tags=None, exclude_tags=None):
+        flow = {"dir": path}
+        if include_tags is not None:
+            flow["include_tags"] = include_tags
+        if exclude_tags is not None:
+            flow["exclude_tags"] = exclude_tags
+        self._run(flow, env, FLOW_TIMEOUT_S)
+
+    def _run(self, flow, env, timeout):
+        arguments = {"device_id": self.device_id(), **flow}
+        if env:
+            arguments["env"] = {k: str(v) for k, v in env.items()}
+        self.mcp.call_tool("run", arguments, timeout=timeout)
+
+    def screen(self):
+        """Returns the settled current screen's element tree, from Maestro's inspect_screen.
+
+        Actions return before transitions finish, so inspecting at once can see the
+        previous screen. Waiting for animations first makes snapshot checks deterministic.
+        """
+        self.run_commands({"waitForAnimationToEnd": {"timeout": SETTLE_TIMEOUT_MS}}, log=False)
+        content = self.mcp.call_tool("inspect_screen", {"device_id": self.device_id()})
+        return json.loads(content[0]["text"])["elements"]
+
+    def elements(self):
+        """Returns every element on the current screen, flattened."""
+        return list(walk(self.screen()))
+
+    def timeout_ms(self, timeout=None):
+        return int((self.timeout if timeout is None else timeout).total_seconds() * 1000)
+
+    def wait_until(self, selector, visible=True, timeout=None, error=None):
+        """Waits for a selector to become visible (or not visible) using Maestro's extendedWaitUntil."""
+        state = "visible" if visible else "notVisible"
+        try:
+            self.run_commands({"extendedWaitUntil": {state: selector, "timeout": self.timeout_ms(timeout)}})
+        except MaestroError as err:
+            raise AssertionError(error or str(err)) from None
+
+    def find(self, selector):
+        return [e for e in self.elements() if matches(e, selector)]

MaestroLibrary/keywords/__init__.py

@@ -0,0 +1,8 @@
+from ._applicationmanagement import ApplicationManagementKeywords
+from ._element import ElementKeywords
+from ._runonfailure import RunOnFailureKeywords
+from ._screenshot import ScreenshotKeywords
+from ._waiting import WaitingKeywords
+from ._touch import TouchKeywords
+from ._keyevent import KeyeventKeywords
+from ._device import DeviceKeywords

MaestroLibrary/keywords/_applicationmanagement.py

@@ -0,0 +1,203 @@
+import json
+import os
+import shutil
+import subprocess
+from datetime import timedelta
+
+from robot.api import logger
+from robotlibcore import keyword
+
+
+PERMISSION_STATES = ("allow", "deny", "unset")
+
+
+def check_permissions(permissions: dict[str, str]) -> dict[str, str]:
+    for name, state in permissions.items():
+        if state not in PERMISSION_STATES:
+            raise ValueError(f"Permission '{name}' must be allow, deny or unset, not '{state}'.")
+    return permissions
+
+
+class ApplicationManagementKeywords:
+    def __init__(self, lib):
+        self.lib = lib
+
+    @keyword
+    def open_application(self, app_id: str, clear_state: bool = False, stop_app: bool = True,
+                         permissions: dict[str, str] | None = None):
+        """Launches the app with package name / bundle id `app_id` and makes it the current app.
+
+        `clear_state` wipes the app's data first, which is a fresh install for practical purposes.
+        `stop_app` restarts the app if it is already running. Without `permissions` Maestro
+        grants every runtime permission on launch. `permissions` sets them instead, with
+        values allow, deny or unset, for example ``{'all': 'deny'}``.
+
+        Unlike AppiumLibrary there's no remote URL or capabilities: Maestro talks to the
+        device directly.
+
+        | `Open Application` | com.example.app | clear_state=True |
+        | `Open Application` | com.example.app | permissions={'all': 'deny'} |
+        """
+        launch = {"appId": app_id, "clearState": clear_state, "stopApp": stop_app}
+        if permissions is not None:
+            launch["permissions"] = check_permissions(permissions)
+        self.lib.run_commands({"launchApp": launch}, app_id=app_id)
+        self.lib.app_id = app_id
+        self.lib.wait_for_app_focus(app_id)
+
+    @keyword
+    def clear_application_state(self, app_id: str | None = None):
+        """Wipes the data of `app_id`, or of the current app, as if it were freshly installed.
+
+        | `Clear Application State` | com.example.app |
+        """
+        app_id = self._app_id(app_id)
+        self.lib.run_commands({"clearState": app_id}, app_id=app_id)
+
+    @keyword
+    def kill_application(self, app_id: str | None = None):
+        """Kills `app_id`, or the current app, the way the system does when it reclaims memory.
+        It only kills an app in the background: a foreground app keeps running. Unlike
+        `Terminate Application`, which stops the app, this tests that the app restores its state.
+
+        | `Kill Application` | com.example.app |
+        """
+        app_id = self._app_id(app_id)
+        self.lib.run_commands({"killApp": app_id}, app_id=app_id)
+
+    @keyword
+    def set_application_permissions(self, app_id: str | None = None, **permissions: str):
+        """Sets runtime permissions of `app_id`, or of the current app, to allow, deny or unset.
+
+        Each named argument is a permission and its state, for example ``all=deny``, or
+        ``camera=allow``. ``unset`` returns the permission to the system default.
+
+        | `Set Application Permissions` | com.example.app | camera=allow | notifications=unset |
+        """
+        app_id = self._app_id(app_id)
+        if not permissions:
+            raise ValueError("No permissions given. Name them as arguments, for example camera=allow.")
+        self.lib.run_commands({"setPermissions": {"appId": app_id, "permissions": check_permissions(permissions)}},
+                              app_id=app_id)
+
+    def _app_id(self, app_id):
+        app_id = app_id or self.lib.app_id
+        if not app_id:
+            raise ValueError("No app_id given and no application is open.")
+        return app_id
+
+    @keyword
+    def close_application(self):
+        """Stops the current app."""
+        if self.lib.app_id:
+            self.lib.run_commands({"stopApp": self.lib.app_id})
+            self.lib.app_id = None
+
+    @keyword
+    def close_all_applications(self):
+        """Stops the current app and shuts the Maestro session down. Use it in suite teardown."""
+        try:
+            if self.lib.mcp.running:
+                self.close_application()
+        finally:
+            self.lib.mcp.close()
+
+    @keyword
+    def activate_application(self, app_id: str):
+        """Brings `app_id` to the foreground without restarting it, and makes it the current app."""
+        self.lib.run_commands({"launchApp": {"appId": app_id, "stopApp": False}}, app_id=app_id)
+        self.lib.app_id = app_id
+        self.lib.wait_for_app_focus(app_id)
+
+    @keyword
+    def terminate_application(self, app_id: str):
+        """Stops `app_id`."""
+        self.lib.run_commands({"stopApp": app_id}, app_id=app_id)
+
+    @keyword
+    def go_back(self):
+        """Presses the Android back button."""
+        self.lib.run_commands("back")
+
+    @keyword
+    def go_to_url(self, url: str):
+        """Opens `url`. A deep link opens in its app, a web URL in the default browser."""
+        self.lib.run_commands({"openLink": url})
+
+    @keyword
+    def get_source(self) -> str:
+        """Returns the current screen's view hierarchy as JSON (Maestro ``inspect_screen``)."""
+        return json.dumps(self.lib.screen(), indent=1)
+
+    @keyword
+    def log_source(self, loglevel: str = "INFO") -> str:
+        """Logs and returns the current screen's view hierarchy."""
+        source = self.get_source()
+        logger.write(source, loglevel)
+        return source
+
+    @keyword
+    def set_maestro_timeout(self, seconds: timedelta) -> timedelta:
+        """Sets the default timeout of the `Wait Until` and `Expect` keywords and returns the old one."""
+        old, self.lib.timeout = self.lib.timeout, seconds
+        return old
+
+    @keyword
+    def get_maestro_timeout(self) -> timedelta:
+        """Returns the default timeout of the `Wait Until` and `Expect` keywords."""
+        return self.lib.timeout
+
+    @keyword
+    def run_flow(self, flow: str, *, include_tags: list[str] | str | None = None,
+                 exclude_tags: list[str] | str | None = None, **env: str):
+        """Runs a Maestro flow file, a directory of flows, or inline YAML commands, on the current device.
+
+        Use it for the Maestro commands that have no keyword. Inline YAML without a config section
+        gets the current app's ``appId``. Named arguments become flow environment
+        variables (``${NAME}`` in the flow).
+
+        A directory runs every flow in it. `include_tags` and `exclude_tags` pick flows by
+        their ``tags``, and are only valid with a directory. Give several tags as a list
+        variable, such as ``@{TAGS}``.
+
+        | `Run Flow` | ${CURDIR}/flows/onboarding.yaml | USER=demo |
+        | `Run Flow` | ${CURDIR}/flows/ | include_tags=smoke | exclude_tags=slow |
+        | `Run Flow` | - tapOn:\\n    text: Next\\n    index: 1 |
+        """
+        include_tags = [include_tags] if isinstance(include_tags, str) else include_tags
+        exclude_tags = [exclude_tags] if isinstance(exclude_tags, str) else exclude_tags
+        if os.path.isdir(flow):
+            self.lib.run_dir(os.path.abspath(flow), env, include_tags, exclude_tags)
+            return
+        if include_tags is not None or exclude_tags is not None:
+            raise ValueError("include_tags and exclude_tags only apply to a flow directory.")
+        if os.path.isfile(flow):
+            # Passed by path so the flow's relative runFlow/runScript paths resolve next to it.
+            self.lib.run_files([os.path.abspath(flow)], env)
+            return
+        if "\n" not in flow and not flow.lstrip().startswith("-") and flow.rstrip().endswith((".yaml", ".yml", "/", "\\")):
+            raise ValueError(f"Flow file or directory not found: {flow}")
+        if not any(line.strip() == "---" for line in flow.splitlines()):
+            flow = f"appId: {json.dumps(self.lib.app_id or 'maestro.no.app')}\n---\n{flow}"
+        self.lib.run_yaml(flow, env)
+
+    @keyword
+    def execute_adb_shell(self, command: str, *args: str, timeout: timedelta = timedelta(seconds=30)) -> str:
+        """Runs `adb shell command args` on the current Android device and returns its output.
+
+        Fails if the command doesn't finish within `timeout` (AppiumLibrary has a separate
+        `Execute Adb Shell Timeout` keyword for this).
+        """
+        adb = shutil.which("adb")
+        if not adb:
+            raise AssertionError("adb is not on PATH. Install Android platform-tools.")
+        try:
+            result = subprocess.run(
+                [adb, "-s", self.lib.device_id(), "shell", command, *args],
+                capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout.total_seconds(),
+            )
+        except subprocess.TimeoutExpired:
+            raise AssertionError(f"adb shell {command} timed out after {timeout.total_seconds():g} s.") from None
+        if result.returncode:
+            raise AssertionError(f"adb shell {command} failed ({result.returncode}): {result.stderr.strip()}")
+        return result.stdout

MaestroLibrary/keywords/_device.py

@@ -0,0 +1,92 @@
+import os
+
+from robotlibcore import keyword
+
+ORIENTATIONS = ("PORTRAIT", "LANDSCAPE_LEFT", "LANDSCAPE_RIGHT", "UPSIDE_DOWN")
+
+
+def maestro_path(path):
+    """`path` as Maestro needs it: absolute, with forward slashes (also on Windows)."""
+    return os.path.abspath(path).replace(os.sep, "/")
+
+
+class DeviceKeywords:
+    def __init__(self, lib):
+        self.lib = lib
+
+    @keyword
+    def set_location(self, latitude: float, longitude: float, altitude: float | None = None):
+        """Sets the device's location (a mock location on Android).
+
+        `altitude` is accepted for AppiumLibrary compatibility and ignored: Maestro sets only
+        latitude and longitude.
+
+        | `Set Location` | 33.3152 | 44.3661 |
+        """
+        self.lib.run_commands({"setLocation": {"latitude": str(latitude), "longitude": str(longitude)}})
+
+    @keyword
+    def travel(self, *points: str, speed: float | None = None):
+        """Moves the device's location through `points` (``latitude,longitude``) at `speed` metres per
+        second, or Maestro's default speed.
+
+        | `Travel` | 33.3152,44.3661 | 33.3200,44.3700 | speed=20 |
+        """
+        if len(points) < 2:
+            raise ValueError("Travel needs at least two points.")
+        command = {"points": list(points)}
+        if speed is not None:
+            command["speed"] = speed
+        self.lib.run_commands({"travel": command})
+
+    @keyword
+    def landscape(self):
+        """Rotates the device to landscape (``LANDSCAPE_LEFT``)."""
+        self.set_orientation("LANDSCAPE_LEFT")
+
+    @keyword
+    def portrait(self):
+        """Rotates the device to portrait."""
+        self.set_orientation("PORTRAIT")
+
+    @keyword
+    def set_orientation(self, orientation: str):
+        """Rotates the device: ``PORTRAIT``, ``LANDSCAPE_LEFT``, ``LANDSCAPE_RIGHT`` or ``UPSIDE_DOWN``
+        (case and spaces don't matter).
+
+        | `Set Orientation` | landscape right |
+        """
+        value = orientation.strip().upper().replace(" ", "_")
+        if value not in ORIENTATIONS:
+            raise ValueError(f"Unknown orientation '{orientation}'. Use one of: {', '.join(ORIENTATIONS)}.")
+        self.lib.run_commands({"setOrientation": value})
+
+    @keyword
+    def set_airplane_mode(self, enabled: bool):
+        """Turns airplane mode on or off. With it on, the device has no network.
+
+        | `Set Airplane Mode` | True |
+        """
+        self.lib.run_commands({"setAirplaneMode": "enabled" if enabled else "disabled"})
+
+    @keyword
+    def set_dark_mode(self, enabled: bool):
+        """Turns the system dark theme on or off.
+
+        | `Set Dark Mode` | True |
+        """
+        self.lib.run_commands({"setDarkMode": "enabled" if enabled else "disabled"})
+
+    @keyword
+    def add_media(self, *paths: str):
+        """Adds image or video files to the device's gallery, for tests that pick or upload media.
+        On Android they land in ``Pictures/`` under their own file names.
+
+        | `Add Media` | ${CURDIR}/data/receipt.png |
+        """
+        if not paths:
+            raise ValueError("Add Media needs at least one file.")
+        missing = [path for path in paths if not os.path.isfile(path)]
+        if missing:
+            raise ValueError(f"Media file does not exist: {', '.join(missing)}")
+        self.lib.run_commands({"addMedia": [maestro_path(path) for path in paths]})