robotframework-maestrolibrary 0.2.0__tar.gz

robotframework_maestrolibrary-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The robotframework-maestrolibrary authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

robotframework_maestrolibrary-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: robotframework-maestrolibrary
+Version: 0.2.0
+Summary: Robot Framework mobile keywords on top of Maestro, with an AppiumLibrary-style API
+License-Expression: MIT
+Classifier: Framework :: Robot Framework
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Topic :: Software Development :: Testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: robotframework>=7.5
+Requires-Dist: robotframework-pythonlibcore>=4.6.0
+Dynamic: license-file
+
+# robotframework-maestrolibrary
+
+Robot Framework keywords for mobile apps, driven by [Maestro](https://maestro.dev).
+If you know [AppiumLibrary](https://github.com/serhatbolsu/robotframework-appiumlibrary),
+you already know the keyword names, the arguments and the `strategy=value` locators.
+There's no Appium server and no capabilities to manage. Maestro waits for the UI on every action.
+
+## Requirements
+- Maestro CLI on PATH (`maestro --version`) and Java 17+
+- A running emulator/simulator or a connected device
+- Android: `adb` (platform-tools) on PATH. `Open Application` uses it to wait for the app's
+  window, and `Execute Adb Shell` needs it. Without it, Open Application warns and returns as
+  soon as Maestro does.
+
+## Install
+```
+pip install robotframework-maestrolibrary
+```
+For development: `pip install -e .`
+
+A version tag (`v0.2.0`, matching `__version__`) builds the package in CI and uploads it to the
+project's registry, and to PyPI when the `PYPI_TOKEN` CI variable is set.
+MIT: see LICENSE.
+
+## Example
+```robotframework
+*** Settings ***
+Library    MaestroLibrary    timeout=10s
+
+*** Test Cases ***
+Search Settings
+    Open Application    com.android.settings
+    Click Text    Search settings    exact_match=True
+    Input Text    id=com.google.android.settings.intelligence:id/open_search_view_edit_text    wifi
+    Wait Until Page Contains    Wi-Fi
+    [Teardown]    Close All Applications
+```
+
+## Locators
+`text=`, `accessibility_id=`, `id=` (literal, whole value), `regex=`, `id_regex=`
+(Maestro regular expressions), `point=50%,50%`. A bare value means text. Flutter apps
+get ids from `Semantics(identifier: ...)`. xpath, class, android, ios, predicate, chain,
+css, name and identifier fail with a clear message.
+
+## Coming from AppiumLibrary
+Same names and arguments: Close/Activate/Terminate Application, Close All
+Applications, Go Back, Go To Url, Get Source, Log Source, Execute Adb Shell, Click
+Element, Click Text, Input Text, Input Password, Input Text Into Current Element, Clear
+Text, Hide Keyboard, Page Should (Not) Contain Text/Element, Element Should Be
+Visible/Enabled/Disabled, Text Should Be Visible, Element Text Should Be, Element Should
+(Not) Contain Text, Get Text, Get Element Attribute, Scroll Element Into View, Expect
+Element, Expect Text, the five Wait Until keywords, Swipe, Swipe By Percent, Scroll
+Down/Up, Tap, Long Press, Press Keycode, Capture Page Screenshot, Register Keyword To Run
+On Failure, Set Location, Landscape, Portrait.
+
+Differences:
+- `Open Application    <app id>    clear_state=False    stop_app=True`: no remote URL or
+  capabilities. Like Appium, it returns once the app has window focus.
+- Set/Get Appium Timeout become Set/Get Maestro Timeout.
+- Press Keycode supports the keycodes that Maestro can send. `Press Key` takes Maestro key names.
+- Should/Get keywords check the settled screen once. Wait/Expect keywords and every action wait.
+- Screenshots are JPEG (`maestro-screenshot-<n>.jpg`, or `EMBED`).
+- Swipe `duration` takes a time (`300ms`); a bare number is milliseconds, as in AppiumLibrary.
+- `speed=0.5s` (import argument) pauses before every Maestro command, like SeleniumLibrary's
+  speed. Use it when a slow or overloaded emulator stops responding.
+- Start Screen Recording takes `time_limit` (AppiumLibrary: `timeLimit`), 3 minutes by default.
+  Stop Screen Recording saves `filename` as given (AppiumLibrary appends `.mp4`). Both are
+  Android only (adb `screenrecord`): Maestro ends its own recording with each flow, and every
+  keyword is its own flow. Put Stop in a teardown.
+- Set Location ignores `altitude`.
+
+Maestro-only keywords:
+- `Run Flow`: a YAML file, inline commands, or a directory of flows with `include_tags` /
+  `exclude_tags`, plus env variables.
+- App state: `Clear Application State`, `Kill Application` (the system killing a background app),
+  `Set Application Permissions` (`camera=deny`, `all=allow`), `Open Application    permissions=...`.
+- Device: `Travel` (move the location along points), `Set Orientation`, `Set Airplane Mode`,
+  `Set Dark Mode`, `Add Media` (put images or videos in the gallery).
+- Visual: `Capture Element Screenshot` (PNG), `Screenshot Should Match` (compare with a reference
+  PNG, whole screen or one element, with a threshold).
+- `Wait For Animation To End`, `Is Keyboard Shown`.
+
+Not ported: webview contexts, xpath, multiple app aliases, touch id, WebElement keywords,
+Drag And Drop, Flick, sleep-between-wait-loop settings.
+
+## Maestro CLI coverage
+The library talks to `maestro mcp`. What the other `maestro` subcommands do, and where it lives here:
+
+| `maestro` | Here |
+|---|---|
+| `test` (flows, tags, `-e`) | `Run Flow` |
+| `print-hierarchy`, `query` | `Get Source`, `Get Text`, `Get Element Attribute`, the Should keywords |
+| `list-devices` | the `device` import argument; the first connected device by default |
+| `record` | `Start/Stop Screen Recording` |
+| `check-syntax` | `Run Flow` fails with Maestro's parse error and its line |
+| `start-device` | not a test step: boot the emulator before the run, e.g. `maestro start-device --platform android` in CI |
+| `studio`, `chat`, `driver`, `cloud`, `login`, ... | interactive or Maestro Cloud tools, not used |
+
+Flow commands without a keyword, still reachable with `Run Flow`: the AI assertions (need a
+Maestro Cloud key), `inputRandom*`, clipboard commands (the copied text stays inside one flow),
+`repeat`/`retry` (use Robot's FOR and `Wait Until Keyword Succeeds`), `runScript`/`evalScript`,
+`toggleAirplaneMode`, `assertDarkMode`/`assertLightMode`, `clearKeychain` (iOS), `doubleTapOn`.
+
+Each `maestro mcp` process reinstalls Maestro's driver app on the device once, when it first
+connects (Maestro hard-codes it). The library keeps one process for the whole run.
+
+## Development
+```
+python -m unittest discover -s utest                        # no device needed
+robot --pythonpath src -d results atest                     # needs a running Android emulator
+python -m robot.libdoc --pythonpath src MaestroLibrary results/MaestroLibrary.html
+```

robotframework_maestrolibrary-0.2.0/README.md

@@ -0,0 +1,112 @@
+# robotframework-maestrolibrary
+
+Robot Framework keywords for mobile apps, driven by [Maestro](https://maestro.dev).
+If you know [AppiumLibrary](https://github.com/serhatbolsu/robotframework-appiumlibrary),
+you already know the keyword names, the arguments and the `strategy=value` locators.
+There's no Appium server and no capabilities to manage. Maestro waits for the UI on every action.
+
+## Requirements
+- Maestro CLI on PATH (`maestro --version`) and Java 17+
+- A running emulator/simulator or a connected device
+- Android: `adb` (platform-tools) on PATH. `Open Application` uses it to wait for the app's
+  window, and `Execute Adb Shell` needs it. Without it, Open Application warns and returns as
+  soon as Maestro does.
+
+## Install
+```
+pip install robotframework-maestrolibrary
+```
+For development: `pip install -e .`
+
+A version tag (`v0.2.0`, matching `__version__`) builds the package in CI and uploads it to the
+project's registry, and to PyPI when the `PYPI_TOKEN` CI variable is set.
+MIT: see LICENSE.
+
+## Example
+```robotframework
+*** Settings ***
+Library    MaestroLibrary    timeout=10s
+
+*** Test Cases ***
+Search Settings
+    Open Application    com.android.settings
+    Click Text    Search settings    exact_match=True
+    Input Text    id=com.google.android.settings.intelligence:id/open_search_view_edit_text    wifi
+    Wait Until Page Contains    Wi-Fi
+    [Teardown]    Close All Applications
+```
+
+## Locators
+`text=`, `accessibility_id=`, `id=` (literal, whole value), `regex=`, `id_regex=`
+(Maestro regular expressions), `point=50%,50%`. A bare value means text. Flutter apps
+get ids from `Semantics(identifier: ...)`. xpath, class, android, ios, predicate, chain,
+css, name and identifier fail with a clear message.
+
+## Coming from AppiumLibrary
+Same names and arguments: Close/Activate/Terminate Application, Close All
+Applications, Go Back, Go To Url, Get Source, Log Source, Execute Adb Shell, Click
+Element, Click Text, Input Text, Input Password, Input Text Into Current Element, Clear
+Text, Hide Keyboard, Page Should (Not) Contain Text/Element, Element Should Be
+Visible/Enabled/Disabled, Text Should Be Visible, Element Text Should Be, Element Should
+(Not) Contain Text, Get Text, Get Element Attribute, Scroll Element Into View, Expect
+Element, Expect Text, the five Wait Until keywords, Swipe, Swipe By Percent, Scroll
+Down/Up, Tap, Long Press, Press Keycode, Capture Page Screenshot, Register Keyword To Run
+On Failure, Set Location, Landscape, Portrait.
+
+Differences:
+- `Open Application    <app id>    clear_state=False    stop_app=True`: no remote URL or
+  capabilities. Like Appium, it returns once the app has window focus.
+- Set/Get Appium Timeout become Set/Get Maestro Timeout.
+- Press Keycode supports the keycodes that Maestro can send. `Press Key` takes Maestro key names.
+- Should/Get keywords check the settled screen once. Wait/Expect keywords and every action wait.
+- Screenshots are JPEG (`maestro-screenshot-<n>.jpg`, or `EMBED`).
+- Swipe `duration` takes a time (`300ms`); a bare number is milliseconds, as in AppiumLibrary.
+- `speed=0.5s` (import argument) pauses before every Maestro command, like SeleniumLibrary's
+  speed. Use it when a slow or overloaded emulator stops responding.
+- Start Screen Recording takes `time_limit` (AppiumLibrary: `timeLimit`), 3 minutes by default.
+  Stop Screen Recording saves `filename` as given (AppiumLibrary appends `.mp4`). Both are
+  Android only (adb `screenrecord`): Maestro ends its own recording with each flow, and every
+  keyword is its own flow. Put Stop in a teardown.
+- Set Location ignores `altitude`.
+
+Maestro-only keywords:
+- `Run Flow`: a YAML file, inline commands, or a directory of flows with `include_tags` /
+  `exclude_tags`, plus env variables.
+- App state: `Clear Application State`, `Kill Application` (the system killing a background app),
+  `Set Application Permissions` (`camera=deny`, `all=allow`), `Open Application    permissions=...`.
+- Device: `Travel` (move the location along points), `Set Orientation`, `Set Airplane Mode`,
+  `Set Dark Mode`, `Add Media` (put images or videos in the gallery).
+- Visual: `Capture Element Screenshot` (PNG), `Screenshot Should Match` (compare with a reference
+  PNG, whole screen or one element, with a threshold).
+- `Wait For Animation To End`, `Is Keyboard Shown`.
+
+Not ported: webview contexts, xpath, multiple app aliases, touch id, WebElement keywords,
+Drag And Drop, Flick, sleep-between-wait-loop settings.
+
+## Maestro CLI coverage
+The library talks to `maestro mcp`. What the other `maestro` subcommands do, and where it lives here:
+
+| `maestro` | Here |
+|---|---|
+| `test` (flows, tags, `-e`) | `Run Flow` |
+| `print-hierarchy`, `query` | `Get Source`, `Get Text`, `Get Element Attribute`, the Should keywords |
+| `list-devices` | the `device` import argument; the first connected device by default |
+| `record` | `Start/Stop Screen Recording` |
+| `check-syntax` | `Run Flow` fails with Maestro's parse error and its line |
+| `start-device` | not a test step: boot the emulator before the run, e.g. `maestro start-device --platform android` in CI |
+| `studio`, `chat`, `driver`, `cloud`, `login`, ... | interactive or Maestro Cloud tools, not used |
+
+Flow commands without a keyword, still reachable with `Run Flow`: the AI assertions (need a
+Maestro Cloud key), `inputRandom*`, clipboard commands (the copied text stays inside one flow),
+`repeat`/`retry` (use Robot's FOR and `Wait Until Keyword Succeeds`), `runScript`/`evalScript`,
+`toggleAirplaneMode`, `assertDarkMode`/`assertLightMode`, `clearKeychain` (iOS), `doubleTapOn`.
+
+Each `maestro mcp` process reinstalls Maestro's driver app on the device once, when it first
+connects (Maestro hard-codes it). The library keeps one process for the whole run.
+
+## Development
+```
+python -m unittest discover -s utest                        # no device needed
+robot --pythonpath src -d results atest                     # needs a running Android emulator
+python -m robot.libdoc --pythonpath src MaestroLibrary results/MaestroLibrary.html
+```

robotframework_maestrolibrary-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=84"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robotframework-maestrolibrary"
+dynamic = ["version"]
+description = "Robot Framework mobile keywords on top of Maestro, with an AppiumLibrary-style API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "robotframework>=7.5",
+    "robotframework-pythonlibcore>=4.6.0",
+]
+classifiers = [
+    "Framework :: Robot Framework",
+    "Framework :: Robot Framework :: Library",
+    "Topic :: Software Development :: Testing",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "MaestroLibrary.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+MaestroLibrary = ["py.typed"]
+
+[tool.bandit]
+# B404/B603: the library drives `maestro` and `adb` through subprocess on purpose, always with
+# list arguments and no shell; Execute Adb Shell runs the caller's adb command by design.
+skips = ["B404", "B603"]

robotframework_maestrolibrary-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

robotframework_maestrolibrary-0.2.0/src/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)]

robotframework_maestrolibrary-0.2.0/src/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