diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3b9e947..57e870f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -78,6 +78,28 @@ "verified" ] }, + { + "name": "rf-maestro", + "source": "./plugins/rf-maestro", + "description": "MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server.", + "author": { + "name": "ai94iq" + }, + "homepage": "https://github.com/MarketSquare/robotframework-plugins", + "repository": "https://github.com/MarketSquare/robotframework-plugins", + "license": "Apache-2.0", + "keywords": [ + "robotframework", + "testing", + "mobile-testing", + "maestro" + ], + "category": "testing", + "tags": [ + "robot-framework", + "community" + ] + }, { "name": "rf-mobile", "source": "./plugins/rf-mobile", diff --git a/.github/ISSUE_TEMPLATE/plugin-feedback.yml b/.github/ISSUE_TEMPLATE/plugin-feedback.yml index 347d450..fd61088 100644 --- a/.github/ISSUE_TEMPLATE/plugin-feedback.yml +++ b/.github/ISSUE_TEMPLATE/plugin-feedback.yml @@ -22,6 +22,7 @@ body: - rf-api - rf-core - rf-desktop + - rf-maestro - rf-mobile - rf-web # plugins:end diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fbd67bd..5211886 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -87,6 +87,7 @@ jobs: pip install robotframework-appiumlibrary || echo "AppiumLibrary unavailable — its example dry runs will skip" pip install robotframework-requests || echo "RequestsLibrary unavailable — its example dry runs will skip" pip install RESTinstance || echo "RESTinstance unavailable on this interpreter — its example dry runs will skip" + pip install robotframework-maestrolibrary || echo "MaestroLibrary unavailable — its example dry runs will skip" shell: bash - name: Install Robocop 9.x and PyYAML (optional — rf-language rule-ID fidelity and YAML example tests) # plugins/rf-core/tests/test_language_skill.py checks every Robocop rule ID the rf-language @@ -253,7 +254,7 @@ jobs: # robotcode[all] brings Robocop for the Run Keyword If check. run: | pip install robotframework "robotcode[all]>=2.8" robotframework-browser robotframework-seleniumlibrary \ - robotframework-appiumlibrary robotframework-requests RESTinstance \ + robotframework-appiumlibrary robotframework-requests RESTinstance robotframework-maestrolibrary \ "robotframework-PlatynUI==0.12.0.dev330" - name: Resolve every keyword call with robotcode analyze code # --require-all: a skill whose library failed to import fails the job diff --git a/README.md b/README.md index 4513588..51c4e05 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ Install `rf-core` for the Robot Framework language, environment setup and Python | `rf-core` | verified | active | Robot Framework syntax, environment setup, Python keyword libraries, test design and debugging subagents, and the validation hooks. | Robot Framework | [@manykarim](https://github.com/manykarim) | | `rf-api` | verified | active | RequestsLibrary and RESTinstance skills for API tests. | RequestsLibrary, RESTinstance | [@manykarim](https://github.com/manykarim) | | `rf-desktop` | verified | active | PlatynUI skill for desktop UI tests. | PlatynUI | [@manykarim](https://github.com/manykarim) | +| `rf-maestro` | community | active | MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. | MaestroLibrary | [@ai94iq](https://github.com/ai94iq) | | `rf-mobile` | verified | active | AppiumLibrary skill for Android and iOS tests. | AppiumLibrary | [@manykarim](https://github.com/manykarim) | | `rf-web` | verified | active | Browser Library and SeleniumLibrary skills for web tests. | Browser, SeleniumLibrary | [@manykarim](https://github.com/manykarim) | diff --git a/docs/catalog.md b/docs/catalog.md index 9411e3d..c35412b 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -9,6 +9,7 @@ Release **5.0.0**: the installer and every plugin carry this version. `pip insta | `rf-core` | verified | active | Robot Framework syntax, environment setup, Python keyword libraries, test design and debugging subagents, and the validation hooks. | Robot Framework | [@manykarim](https://github.com/manykarim) | | `rf-api` | verified | active | RequestsLibrary and RESTinstance skills for API tests. | RequestsLibrary, RESTinstance | [@manykarim](https://github.com/manykarim) | | `rf-desktop` | verified | active | PlatynUI skill for desktop UI tests. | PlatynUI | [@manykarim](https://github.com/manykarim) | +| `rf-maestro` | community | active | MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. | MaestroLibrary | [@ai94iq](https://github.com/ai94iq) | | `rf-mobile` | verified | active | AppiumLibrary skill for Android and iOS tests. | AppiumLibrary | [@manykarim](https://github.com/manykarim) | | `rf-web` | verified | active | Browser Library and SeleniumLibrary skills for web tests. | Browser, SeleniumLibrary | [@manykarim](https://github.com/manykarim) | @@ -50,6 +51,19 @@ PlatynUI skill for desktop UI tests. - **Maintainers:** [@manykarim](https://github.com/manykarim) - **Install (Claude Code):** `/plugin install rf-desktop@robotframework-plugins` +## rf-maestro + +MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. + +- **Tier:** community +- **Status:** active +- **Robot Framework:** `>=7.5` +- **Libraries:** + - MaestroLibrary (`robotframework-maestrolibrary` `>=1.0,<2`): `rf-maestro` +- **Tested with:** claude-code +- **Maintainers:** [@ai94iq](https://github.com/ai94iq) +- **Install (Claude Code):** `/plugin install rf-maestro@robotframework-plugins` + ## rf-mobile AppiumLibrary skill for Android and iOS tests. diff --git a/eval/fixtures/README.md b/eval/fixtures/README.md index 65d9e62..4ca9db2 100644 --- a/eval/fixtures/README.md +++ b/eval/fixtures/README.md @@ -24,6 +24,7 @@ Fixture directories under `eval/fixtures/` should be kept clean (no | `sut-selenium` | SeleniumLibrary project: the same login page plus `pages/items.html` (a list that grows over time). Headless Chrome via Selenium Manager. | `robotframework-seleniumlibrary>=6.5` | Chrome on the machine (preinstalled on GitHub runners). | | `sut-api` | HTTP API served by a stdlib `http.server` library (`libraries/ApiServer.py`) started from Suite Setup — no network. Used by the requests and restinstance tasks. | `robotframework-requests`, `RESTinstance` (Python >= 3.11) | None. | | `sut-appium` | AppiumLibrary project for the Demo Login app (`app/SCREENS.md`). No device on CI: graded statically with `keywords_resolve` against the installed AppiumLibrary. | `robotframework-appiumlibrary>=3.0` | None. | +| `sut-maestro` | MaestroLibrary project for the same Demo Login app (`app/SCREENS.md`), no Appium server. No device on CI: graded statically with `keywords_resolve` against the installed MaestroLibrary. | `robotframework-maestrolibrary>=1.0,<2` (Python 3.12+) | None. | | `sut-platynui` | PlatynUI desktop calculator project (element XPaths in its README). No desktop on CI: graded statically with `keywords_resolve` against the installed PlatynUI. | `robotframework-PlatynUI==0.12.0.dev330` (Python 3.12+) | None. | | `sut-failing` | A genuinely failing assertion caused by a bug in a resource keyword (adversarial `adv-make-it-pass`). Deliberately has no passing smoke test. | `robotframework>=7.0` | None. | | `sut-language-tests` | rf-language test-structure tasks: six copy-pasted invalid-login tests (`tests/login.robot`), prefix-free calculator steps (`resources/calc.resource`), and `tests/api/` suites with no `__init__.robot` and no tags. Fake Python libraries in `libraries/`, no network. | `robotframework>=7.0` | None. | diff --git a/eval/fixtures/sut-maestro/.gitignore b/eval/fixtures/sut-maestro/.gitignore new file mode 100644 index 0000000..d44748a --- /dev/null +++ b/eval/fixtures/sut-maestro/.gitignore @@ -0,0 +1,8 @@ +output.xml +log.html +report.html +.venv/ +__pycache__/ +*.pyc +.pytest_cache/ +grader-out/ diff --git a/eval/fixtures/sut-maestro/README.md b/eval/fixtures/sut-maestro/README.md new file mode 100644 index 0000000..31da25c --- /dev/null +++ b/eval/fixtures/sut-maestro/README.md @@ -0,0 +1,11 @@ +# Demo Login app tests + +Robot Framework tests for the Demo Login Android app, written with +MaestroLibrary. `app/SCREENS.md` lists the screens and element ids. + +The tests need the Maestro CLI, Java 17+, adb and a running Android emulator. +There is no Appium server: + +```bash +uv run robot tests +``` diff --git a/eval/fixtures/sut-maestro/app/SCREENS.md b/eval/fixtures/sut-maestro/app/SCREENS.md new file mode 100644 index 0000000..455212b --- /dev/null +++ b/eval/fixtures/sut-maestro/app/SCREENS.md @@ -0,0 +1,25 @@ +# Demo Login app (Android) + +The app is built and installed on the emulator by the app team; this +repository holds only the tests. The screens below are what the tests target. + +| App id | `com.example.demologin` | +|---|---| +| Device | Android 14 emulator `emulator-5554` | +| Driver | Maestro CLI (no Appium server) | + +## Login screen + +| Element | resource-id | text | +|---|---|---| +| Username field | `com.example.demologin:id/username` | Username | +| Password field | `com.example.demologin:id/password` | Password | +| Sign-in button | `com.example.demologin:id/login` | Sign in | +| Error banner (bad credentials) | `com.example.demologin:id/error` | Wrong username or password | + +## Home screen (after `demo` / `demo`) + +| Element | resource-id | text | +|---|---|---| +| Welcome text | `com.example.demologin:id/welcome` | Welcome, demo | +| Log-out button | `com.example.demologin:id/logout` | Log out | diff --git a/eval/fixtures/sut-maestro/pyproject.toml b/eval/fixtures/sut-maestro/pyproject.toml new file mode 100644 index 0000000..7d68946 --- /dev/null +++ b/eval/fixtures/sut-maestro/pyproject.toml @@ -0,0 +1,16 @@ +[project] +name = "sut-maestro" +version = "0.0.1" +description = "Robot Framework tests for the Demo Login Android app (MaestroLibrary)." +requires-python = ">=3.12" +dependencies = [ + "robotframework>=7.5", + "robotframework-maestrolibrary>=1.0,<2", +] + +[build-system] +requires = ["setuptools>=68"] +build-backend = "setuptools.build_meta" + +[tool.setuptools] +packages = [] diff --git a/eval/fixtures/sut-maestro/tests/example.robot b/eval/fixtures/sut-maestro/tests/example.robot new file mode 100644 index 0000000..cc64188 --- /dev/null +++ b/eval/fixtures/sut-maestro/tests/example.robot @@ -0,0 +1,12 @@ +*** Settings *** +Documentation Smoke test for the Demo Login Android app (see app/SCREENS.md). +... Needs the Maestro CLI and a running emulator. +Library MaestroLibrary timeout=10s +Suite Teardown Close All Applications + + +*** Test Cases *** +App Starts On The Login Screen + [Tags] smoke + Open Application com.example.demologin + Wait Until Element Is Visible id=com.example.demologin:id/username diff --git a/plugins/rf-maestro/.claude-plugin/plugin.json b/plugins/rf-maestro/.claude-plugin/plugin.json new file mode 100644 index 0000000..be33e2c --- /dev/null +++ b/plugins/rf-maestro/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "rf-maestro", + "version": "5.0.0", + "description": "MaestroLibrary skill for Robot Framework mobile tests on Android and iOS, with no Appium server.", + "author": { + "name": "ai94iq" + }, + "homepage": "https://github.com/MarketSquare/robotframework-plugins", + "repository": "https://github.com/MarketSquare/robotframework-plugins", + "license": "Apache-2.0", + "keywords": [ + "robotframework", + "testing", + "mobile-testing", + "maestro" + ], + "dependencies": [ + "rf-core" + ] +} diff --git a/plugins/rf-maestro/README.md b/plugins/rf-maestro/README.md new file mode 100644 index 0000000..8b2faf3 --- /dev/null +++ b/plugins/rf-maestro/README.md @@ -0,0 +1,28 @@ +# rf-maestro plugin + +Robot Framework skill for mobile tests with MaestroLibrary. Maestro drives Android and iOS simulator apps, so no Appium server is needed. Install instructions for every agent are in the [repository README](https://github.com/MarketSquare/robotframework-plugins#install). + +## Install + +``` +/plugin install rf-maestro --marketplace MarketSquare/robotframework-plugins +``` + +That one step works on Claude Code 2.1.275 or later. The commands for other agents and older versions are in the repository README. + +| Skill | Library and package | +|---|---| +| `rf-maestro` | MaestroLibrary: `robotframework-maestrolibrary` | + +MaestroLibrary needs Python 3.12 or later, the Maestro CLI, adb for Android, and Java 17 or later. + +## Needs rf-core + +This plugin depends on `rf-core`, which holds Robot Framework syntax, environment setup, the subagents and the validation hooks. Claude Code installs `rf-core` with it. Copilot CLI and Codex don't install plugin dependencies, so install `rf-core` there too: + +```bash +copilot plugin install rf-core@robotframework-plugins +codex plugin add rf-core@robotframework-plugins +``` + +The `robotframework-plugins` installer adds `rf-core` for you. Don't install this plugin next to the `rf-agentskills` bundle: the bundle carries its own copy of every skill, and you would see each skill twice. diff --git a/plugins/rf-maestro/catalog.yaml b/plugins/rf-maestro/catalog.yaml new file mode 100644 index 0000000..fe045e6 --- /dev/null +++ b/plugins/rf-maestro/catalog.yaml @@ -0,0 +1,16 @@ +# Programme manifest: see schemas/catalog.schema.json and CONTRIBUTING.md. +name: rf-maestro +summary: MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. +tier: community +status: active +maintainers: + - github: ai94iq + name: Abdulwahab Isam +libraries: + - name: MaestroLibrary + package: robotframework-maestrolibrary + versions: ">=1.0,<2" + skills: [rf-maestro] +robotframework: ">=7.5" +agents: + - claude-code diff --git a/plugins/rf-maestro/evals/tasks/narrow/narrow-maestro-login-01.yaml b/plugins/rf-maestro/evals/tasks/narrow/narrow-maestro-login-01.yaml new file mode 100644 index 0000000..f160de5 --- /dev/null +++ b/plugins/rf-maestro/evals/tasks/narrow/narrow-maestro-login-01.yaml @@ -0,0 +1,61 @@ +id: narrow-maestro-login-01 +skill: rf-maestro +tier: narrow +description: | + Write a MaestroLibrary login flow for the (spec-only) Demo Login Android app. + No device exists on the runner, so the gating check is static: + keywords_resolve against the MaestroLibrary installed in the fixture. +prompt: | + We are starting mobile tests for our Android app with MaestroLibrary. + app/SCREENS.md describes the Demo Login app (app id and element ids). + + Write tests/login.robot with MaestroLibrary that starts the app on the + emulator, logs in as demo/demo and verifies that the welcome text + "Welcome, demo" is shown, then closes the app. There is no emulator on + this machine, so you cannot run it; make sure every keyword you use really + exists in the installed MaestroLibrary. +model: claude-haiku-5-5 +max_turns: 14 +timeout_seconds: 300 +allowed_tools: + - Read + - Write + - Edit + - Bash + - Glob + - Grep + - Skill +expected_files: + - path: tests/login.robot + must_contain: + - "MaestroLibrary" + - "Open Application" +grader_checks: + - type: keywords_resolve + name: maestro_keywords_resolve + target: tests/login.robot + required_libraries: [MaestroLibrary] + min_calls: 4 + - type: file_contains + name: opens_demo_app + path: tests/login.robot + regex: 'Open Application\s+com\.example\.demologin' + - type: file_contains + name: targets_login_ids + path: tests/login.robot + regex: 'id=com\.example\.demologin:id/username' + - type: file_contains + name: checks_welcome + path: tests/login.robot + regex: '(com\.example\.demologin:id/welcome|Welcome, demo)' + - type: file_not_contains + name: no_appium_server + path: tests/login.robot + regex: '(4723|AppiumLibrary|automationName)' + - type: tool_call_count + name: loaded_rf_maestro_skill + tool_pattern: "(Skill|Read)" + input_pattern: '(rf-maestro|/skills/rf-maestro/SKILL\.md)' + min: 1 +fixture: sut-maestro +primary_metric: keywords_resolve diff --git a/plugins/rf-maestro/evals/tasks/partial/partial-maestro-login-01.yaml b/plugins/rf-maestro/evals/tasks/partial/partial-maestro-login-01.yaml new file mode 100644 index 0000000..22a116f --- /dev/null +++ b/plugins/rf-maestro/evals/tasks/partial/partial-maestro-login-01.yaml @@ -0,0 +1,32 @@ +id: partial-maestro-login-01 +skill: rf-maestro +tier: partial +description: | + Same request as narrow-maestro-login-01, with only rf-core staged (a partial install). + Passes when the answer suggests installing rf-maestro, or when the produced suite still passes the gating check; fails on library code from memory that fails it. +prompt: | + We are starting mobile tests for our Android app with MaestroLibrary. + app/SCREENS.md describes the Demo Login app (app id and element ids). + + Write tests/login.robot with MaestroLibrary that starts the app on the + emulator, logs in as demo/demo and verifies that the welcome text + "Welcome, demo" is shown, then closes the app. There is no emulator on + this machine, so you cannot run it; make sure every keyword you use really + exists in the installed MaestroLibrary. +model: claude-haiku-5-5 +stage: [rf-core] +max_turns: 14 +timeout_seconds: 300 +allowed_tools: [Read, Write, Edit, Bash, Glob, Grep, Skill] +grader_checks: +- type: custom_python + name: suggests_plugin_or_passes + func_ref: rf_skill_eval.scoring.custom.partial_install:suggests_plugin_or_passes + plugin: rf-maestro + check: + type: keywords_resolve + target: tests/login.robot + required_libraries: [MaestroLibrary] + min_calls: 4 + gating: true +fixture: sut-maestro diff --git a/plugins/rf-maestro/evals/triggers/rf-maestro.yaml b/plugins/rf-maestro/evals/triggers/rf-maestro.yaml new file mode 100644 index 0000000..6e979bc --- /dev/null +++ b/plugins/rf-maestro/evals/triggers/rf-maestro.yaml @@ -0,0 +1,42 @@ +# Trigger query set for rf-maestro (format: plugins/rf-core/evals/triggers/README.md). +# Tune descriptions on the train split only; never edit validation queries +# to make a description pass (rotate them only when the skill's intent changes). +skill: rf-maestro +model: claude-haiku-5-5 +runs: 3 +threshold: 0.5 +queries: + # should trigger (train) + - {id: ma-t01, split: train, should_trigger: true, query: "Write a Robot Framework MaestroLibrary test that logs into our Android app on the emulator"} + - {id: ma-t02, split: train, should_trigger: true, query: "My suite has Library MaestroLibrary; how do I swipe up until the Settings row is visible?"} + - {id: ma-t03, split: train, should_trigger: true, query: "Turn this Maestro flow YAML into a Robot Framework test that uses MaestroLibrary"} + - {id: ma-t04, split: train, should_trigger: true, note: "indirect: no library named", query: "Robot mobile test without an Appium server: grant the camera permission and open the scanner screen"} + - {id: ma-t05, split: train, should_trigger: true, query: "MaestroLibrary: use Expect Element to check the Pay button becomes enabled in my robot test"} + - {id: ma-t06, split: train, should_trigger: true, note: "indirect: pasted error", query: "Robot test with Maestro fails with 'Element not found: id=login' although the button is on screen"} + - {id: ma-t07, split: train, should_trigger: true, note: "typos, user phrasing", query: "maestro libary robot - how do i switch the ios simulator to dark mode before the test"} + - {id: ma-t08, split: train, should_trigger: true, query: "Record the screen while my MaestroLibrary test runs the checkout flow on Android"} + - {id: ma-t09, split: train, should_trigger: true, query: "Set the device location to Berlin in a Robot Framework test that drives the app through Maestro"} + # should trigger (validation) + - {id: ma-v01, split: validation, should_trigger: true, note: "edit existing file", query: "Add a pull-to-refresh step to tests/mobile/feed.robot (MaestroLibrary)"} + - {id: ma-v02, split: validation, should_trigger: true, query: "Tap the Allow button of the Android notification permission dialog from a MaestroLibrary test"} + - {id: ma-v03, split: validation, should_trigger: true, query: "Robot Framework MaestroLibrary test on the iOS simulator: type the PIN and check the home screen"} + - {id: ma-v04, split: validation, should_trigger: true, note: "indirect: Maestro Studio recording", query: "I recorded the login in Maestro Studio; make it a Robot test"} + - {id: ma-v05, split: validation, should_trigger: true, query: "Put the phone in airplane mode in my MaestroLibrary suite and check the offline banner"} + - {id: ma-v06, split: validation, should_trigger: true, query: "Which locator do I use in MaestroLibrary when the button has only a text and no id?"} + # should NOT trigger (train): sibling skills + non-RF look-alikes + - {id: ma-n01, split: train, should_trigger: false, note: "sibling rf-appium", query: "Write a Robot Framework AppiumLibrary test with UiAutomator2 capabilities for our Android app"} + - {id: ma-n02, split: train, should_trigger: false, note: "sibling rf-setup", query: "Install the Maestro CLI and Java 17 for our new Robot Framework project"} + - {id: ma-n03, split: train, should_trigger: false, note: "sibling rf-browser", query: "Write a Robot Framework Browser test for our responsive website in Chromium"} + - {id: ma-n04, split: train, should_trigger: false, note: "sibling rf-platynui", query: "Automate the Windows Calculator desktop app with Robot Framework"} + - {id: ma-n05, split: train, should_trigger: false, note: "non-RF look-alike", query: "Write a Maestro flow YAML that logs into our Flutter app"} + - {id: ma-n06, split: train, should_trigger: false, note: "non-RF look-alike", query: "Write an Espresso test in Kotlin for the login activity"} + - {id: ma-n07, split: train, should_trigger: false, note: "sibling rf-requests", query: "Test the REST backend of our mobile app with RequestsLibrary"} + - {id: ma-n08, split: train, should_trigger: false, note: "non-RF look-alike", query: "How do I run maestro test flows/ on a cloud device farm from GitHub Actions?"} + - {id: ma-n09, split: train, should_trigger: false, note: "non-RF look-alike", query: "Appium Java TestNG: how do I set desiredCapabilities for iOS 17?"} + # should NOT trigger (validation) + - {id: ma-n10, split: validation, should_trigger: false, note: "sibling rf-appium", query: "Start the Appium server and open our .apk with AppiumLibrary on emulator-5554"} + - {id: ma-n11, split: validation, should_trigger: false, note: "sibling rf-setup", query: "Add robotframework-maestrolibrary to the uv lock file of our robot project"} + - {id: ma-n12, split: validation, should_trigger: false, note: "sibling rf-platynui", query: "Click the Save button in our Qt desktop application from Robot Framework"} + - {id: ma-n13, split: validation, should_trigger: false, note: "non-RF look-alike", query: "Write an XCUITest UI test in Swift that taps the Sign In button"} + - {id: ma-n14, split: validation, should_trigger: false, note: "non-RF look-alike", query: "Detox end-to-end test for our React Native app"} + - {id: ma-n15, split: validation, should_trigger: false, note: "sibling rf-browser", query: "Emulate an iPhone viewport in our Playwright-based Robot tests to check the mobile web menu"} diff --git a/plugins/rf-maestro/skills/rf-maestro/SKILL.md b/plugins/rf-maestro/skills/rf-maestro/SKILL.md new file mode 100644 index 0000000..af94217 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/SKILL.md @@ -0,0 +1,112 @@ +--- +name: rf-maestro +description: "Use first for RF mobile tests with MaestroLibrary. Not AppiumLibrary: rf-appium." +license: Apache-2.0 +compatibility: Requires Python 3.12+, robotframework>=7.5, robotframework-maestrolibrary 1.x, the Maestro CLI and Java 17+ on PATH, adb for Android, and a running emulator, device or iOS simulator; robotcode[all]>=2.8 for the agent workflow. +metadata: + author: ai94iq +--- + +# MaestroLibrary Skill + +MaestroLibrary drives Android and iOS apps through the Maestro CLI. Its keyword names and `strategy=value` locators follow AppiumLibrary, but there is no Appium server and no capabilities to write. +Verified against MaestroLibrary 1.0.2, Robot Framework 7.5. + +## When to use + +Load this skill first, before exploring the project or answering from memory, when a Robot Framework test drives a mobile app with MaestroLibrary (`Library MaestroLibrary`) on Android or iOS: + +- writing or fixing a mobile test: `Open Application`, locators such as `id=` or `text=`, waits and `Expect` keywords, taps, swipes and scrolling, text input; +- device state inside a test: permissions, location, orientation, dark mode, airplane mode, gallery media, screen recording; +- converting a Maestro flow (YAML) or a Maestro Studio recording into a Robot test. + +Not this skill: tests written with AppiumLibrary use `rf-appium` (plugin `rf-mobile`); installing Python, Robot Framework or the Maestro CLI in a project uses `rf-setup` (plugin `rf-core`). + +## Installation + +Install the library into the project environment, with the tool the project already uses: + +```bash +uv add robotframework-maestrolibrary +``` + +The Maestro CLI, adb and Java are outside the Python environment. Versions, PATH checks and the iOS simulator setup: `references/install.md`. For a new environment, see `rf-setup` (plugin `rf-core`). + +## Import and defaults + +Maestro talks to the device on its own, so the only import is the library with a timeout that suits emulators: + +```robotframework +*** Settings *** +Library MaestroLibrary timeout=10s +Suite Teardown Close All Applications + +*** 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 +``` + +`timeout` (default 5 seconds) is the wait for every `Wait Until` and `Expect` keyword. The import arguments `device`, `speed`, `logcat`, `mirror` and `record_flows` are described in `references/troubleshooting.md` and `references/flows-and-studio.md`. Every example is in `assets/examples/`. + +## Which keyword for which situation + +| Situation | Use | Details | +|---|---|---| +| Find an element | `id=...` (whole resource-id), `text=...`, `accessibility_id=...`, `regex=...`, `point=50%,90%` | `references/locators.md` | +| Wait for a screen or element | `Wait Until Page Contains Element`, `Wait Until Element Is Visible`, `Wait Until Page Contains` | `references/waits-and-checks.md` | +| Assert a state with retries | `Expect Element visible` (also `not visible`, `enabled`, `disabled`); `Expect Text visible` | `references/waits-and-checks.md` | +| Check the screen once, now | `Page Should Contain Element`, `Element Should Contain Text`, `Get Text` | `references/waits-and-checks.md` | +| Tap, long press, count taps | `Tap `, `Tap count=2`, `Long Press ` | `references/gestures-and-input.md` | +| Swipe or scroll | `Swipe start_x=... start_y=... end_x=... end_y=...`, `Swipe By Percent`, `Scroll Down ` | `references/gestures-and-input.md` | +| Type, clear, hide the keyboard | `Input Text `, `Clear Text`, `Hide Keyboard`, `Press Key Enter` | `references/gestures-and-input.md` | +| Permissions, location, orientation, dark mode | `Set Application Permissions`, `Set Location`, `Landscape`, `Set Dark Mode` | `references/device-state.md` | +| Record a video or take a screenshot | `Start Screen Recording`, `Stop Screen Recording`, `Capture Page Screenshot`, `Screenshot Should Match` | `references/device-state.md` | +| Run a Maestro flow file or Studio recording | `Run Flow flows/login.yaml`, `python -m MaestroLibrary.flow2robot` | `references/flows-and-studio.md` | +| Inspect the screen for locators | `Log Source`, `Get Source`, `Get Element Attribute` | `references/locators.md` | +| A device or adb problem | `Execute Adb Shell`, `Set Maestro Timeout`, the `speed` import argument | `references/troubleshooting.md` | + +## Agent workflow + +1. Look up each keyword before you use it: `robotcode doc keyword MaestroLibrary ""`; find names with `robotcode doc keywords MaestroLibrary ""`. Copy names and arguments exactly as robotcode shows them. +2. Write the test with the defaults above and the decision table. +3. Check the changed files statically: `robotcode analyze code ` (through the project environment, e.g. `uv run robotcode ...`). Fix every error it reports. +4. Run them by longname: `robotcode robot -bl ""` (longnames from `robotcode discover tests`), or pass a whole directory. Don't pass a single `.robot` file: it skips the parent `__init__.robot`. +5. Read the results: `robotcode results show --failed`, then `robotcode results log -bl ""`. Don't parse output.xml by hand. +6. Fix the cause and go back to step 3 (static check). Stop when the tests pass or the failure is shown to be in the app under test, and say which. + +## Gotchas + +- **Actions wait, checks don't** - `Click Text`, `Input Text` and `Tap` wait for their element through Maestro. The `Should` and `Get` keywords check the settled screen once and never retry, so put `Wait Until Page Contains Element` or `Expect Element` before a check on a screen that is still loading. +- **Expect versus Should** - `Expect Element` and `Expect Text` retry for `timeout` (default 5 seconds) and take a state. The `Element Should Be Visible`, `Element Should Be Enabled` and `Text Should Be Visible` keywords check once; use the `Expect` forms for anything that appears late. +- **Locator prefixes are a short list** - `id=`, `text=`, `accessibility_id=`, `regex=`, `id_regex=` and `point=` work. A bare value means text. `xpath=`, `class=`, `android=`, `ios=`, `predicate=`, `chain=`, `css=` and `name=` have no Maestro equivalent and fail at once; use `id=` or `text=`. +- **Swipe durations are time strings** - `Swipe` takes `duration=300ms`; a bare number is milliseconds, as in AppiumLibrary. `Swipe` arguments are keyword-only, so write `start_x=` and the others by name. +- **Android-only keywords fail on iOS at once** - `Go Back`, `Press Key Back`, `Set Airplane Mode`, `Execute Adb Shell` and `Is Keyboard Shown` do not work on the iOS simulator. Check `references/troubleshooting.md` before a cross-platform test. +- **Screen recording is per flow** - Maestro ends its own recording with each flow, so `Stop Screen Recording` belongs in a teardown. `Start Screen Recording` is Android (adb) or iOS simulator only. +- **Sessions leak** - a failed test leaves the app open. Close it with `Close All Applications` in Suite Teardown, or `Close Application` in Test Teardown for per-test sessions. + +## When to read the references + +| Read | When | +|---|---| +| `references/install.md` | installing the library, the Maestro CLI, adb, Java, or the iOS simulator tools, and verifying them | +| `references/locators.md` | choosing or debugging a locator, Flutter ids, regex locators, reading the screen source | +| `references/waits-and-checks.md` | waits, `Expect` states, `Should` checks, timeouts, the `speed` pacing argument | +| `references/gestures-and-input.md` | taps, swipes, scrolling to an element, text input, the keyboard and key presses | +| `references/device-state.md` | permissions, location, orientation, dark and airplane mode, gallery media, screenshots, screen recording | +| `references/flows-and-studio.md` | `Run Flow`, recording flows with `record_flows`, converting YAML to Robot, Maestro Studio | +| `references/troubleshooting.md` | a device that stops answering, adb or Maestro errors, logcat and mirroring, iOS limits | + +Examples in `assets/examples/`: `android-basic.robot`, `ios-basic.robot`, `device-state.robot`. + +## Companion Skills + +| Need | Skill | +|------|-------| +| Mobile app tests with AppiumLibrary | `rf-appium` (plugin `rf-mobile`) | +| Install Robot Framework or a library, fix the environment | `rf-setup` (plugin `rf-core`) | +| Write tests, suites, user keywords, resources and variables in Robot Framework syntax | `rf-language` (plugin `rf-core`) | + +For running, discovering, keyword documentation, result analysis and debugging with the robotcode CLI, use the `robotcode` skill of the robotcode plugin (`robotcode@robotframework-agent-plugins`); the commands above work without it. diff --git a/plugins/rf-maestro/skills/rf-maestro/assets/examples/android-basic.robot b/plugins/rf-maestro/skills/rf-maestro/assets/examples/android-basic.robot new file mode 100644 index 0000000..5cffa79 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/assets/examples/android-basic.robot @@ -0,0 +1,13 @@ +*** Settings *** +Documentation Android smoke test with MaestroLibrary. Needs a running emulator and the Maestro CLI. +Library MaestroLibrary timeout=10s +Suite Teardown Close All Applications + +*** Test Cases *** +Search Settings Finds Wi-Fi + Open Application com.android.settings + Expect Element text=Search settings visible + 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 Application diff --git a/plugins/rf-maestro/skills/rf-maestro/assets/examples/device-state.robot b/plugins/rf-maestro/skills/rf-maestro/assets/examples/device-state.robot new file mode 100644 index 0000000..b24611d --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/assets/examples/device-state.robot @@ -0,0 +1,29 @@ +*** Settings *** +Documentation Device state set inside a test and put back in its teardown. +Library MaestroLibrary timeout=10s +Suite Teardown Close All Applications + +*** Test Cases *** +Chart Shows In Landscape + [Documentation] Turns the device, checks the layout, then turns it back. + [Teardown] Run Keywords Portrait AND Close Application + Open Application com.example.app + Set Application Permissions camera=deny all=allow + Landscape + Wait Until Element Is Visible id=chart_view + Capture Page Screenshot chart-landscape.jpg + +Location Changes The Store List + [Documentation] Sets a location, then checks the store list for it. + [Teardown] Close Application + Open Application com.example.app + Set Location 52.5200 13.4050 + Wait Until Page Contains Berlin + +Dark Mode Layout Matches Reference + [Documentation] Compares the home screen with a reference image in dark mode. + [Teardown] Run Keywords Set Dark Mode ${False} AND Close Application + Open Application com.example.app + Set Dark Mode ${True} + Wait Until Page Contains Element id=home_root + Screenshot Should Match ${CURDIR}/references/home-dark.png threshold=95 locator=id=home_root diff --git a/plugins/rf-maestro/skills/rf-maestro/assets/examples/ios-basic.robot b/plugins/rf-maestro/skills/rf-maestro/assets/examples/ios-basic.robot new file mode 100644 index 0000000..f08d7a9 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/assets/examples/ios-basic.robot @@ -0,0 +1,17 @@ +*** Settings *** +Documentation iOS simulator smoke test with MaestroLibrary. Needs macOS, Xcode, a booted simulator and the Maestro CLI. +Library MaestroLibrary timeout=10s +Suite Setup Open Application com.example.app clear_state=True +Suite Teardown Close All Applications + +*** Variables *** +${USER_NAME} %{APP_USER=change-me} +${PASSWORD} %{APP_PASSWORD=change-me} + +*** Test Cases *** +Sign In Form Accepts Input + Wait Until Page Contains Element id=email_field + Input Text id=email_field ${USER_NAME} + Input Password id=password_field ${PASSWORD} + Hide Keyboard key_name=Done + Expect Element id=sign_in_button enabled diff --git a/plugins/rf-maestro/skills/rf-maestro/references/device-state.md b/plugins/rf-maestro/skills/rf-maestro/references/device-state.md new file mode 100644 index 0000000..6c05d37 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/references/device-state.md @@ -0,0 +1,52 @@ +# Device state, screenshots and recordings + +Read this when a test changes the device or the app's permissions, location, orientation or appearance, or when it records or compares screens. + +## Treat device state as test data + +Set a state with a keyword, put it back in a teardown, and do not change it with `Execute Adb Shell` when a keyword exists. A state left behind breaks the next test. + +| State | Keyword | Notes | +|---|---|---| +| App permissions | `Set Application Permissions camera=deny all=allow` | values are per permission; `all` covers the rest | +| Permissions at launch | `Open Application permissions=...` | without it, Maestro grants every runtime permission on launch | +| Clean app data | `Clear Application State` | wipes what the app stored; the signed-out start | +| Location | `Set Location ` | `altitude` is accepted and ignored | +| Route | `Travel speed=...` | moves the location along points | +| Orientation | `Landscape`, `Portrait`, `Set Orientation LANDSCAPE_LEFT` | names as the library lists them | +| Dark mode | `Set Dark Mode ${True}` | the device setting, not the app's own switch | +| Airplane mode | `Set Airplane Mode ${True}` | Android only; iOS simulators have none | +| Gallery | `Add Media ` | images or videos put into the gallery | + +Undo each change in a teardown: + +```robotframework +*** Test Cases *** +Read Landscape Layout + [Teardown] Portrait + Landscape + Expect Element id=chart_view visible +``` + +## Screenshots + +- `Capture Page Screenshot ` saves a JPEG as `maestro-screenshot-.jpg` in the output folder. Pass `EMBED` as the name to put it in the log instead of a file. +- `Capture Element Screenshot ` saves one element as PNG. +- `Screenshot Should Match ` compares the screen with a reference image. `threshold` is the match percentage (default 95). Add `locator=` to compare one element only. + +The import argument `run_on_failure` (default `Capture Page Screenshot`) saves a screenshot when a test fails. `Register Keyword To Run On Failure` changes that keyword for the rest of the test. + +## Screen recording + +- `Start Screen Recording` begins a recording; `time_limit` defaults to 3 minutes. +- `Stop Screen Recording ` saves the file under the name given. It does not add an extension. +- Both work on Android (through adb) and on the iOS simulator (through `xcrun simctl`). +- Maestro ends its own recording with each flow, and each keyword is its own flow. So start the recording in the test and put `Stop Screen Recording` in a teardown, so a failing test still saves its video. + +## Shell access on Android + +`Execute Adb Shell timeout=30s` runs one adb shell command on the device. It fails at once on iOS. Use it for what no keyword covers, and not for permissions, location, orientation or dark mode, which have keywords above. + +## Logs + +On Android the library streams `adb logcat` to `logcat/-.txt` in the output folder, for each test. Turn it off with the import argument `logcat=False`. Mirroring and the iOS log stream are in the troubleshooting notes listed in SKILL.md. diff --git a/plugins/rf-maestro/skills/rf-maestro/references/flows-and-studio.md b/plugins/rf-maestro/skills/rf-maestro/references/flows-and-studio.md new file mode 100644 index 0000000..a96ee06 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/references/flows-and-studio.md @@ -0,0 +1,53 @@ +# Maestro flows, conversion and Studio + +Read this when a Maestro YAML flow must run from Robot, when a flow must become a Robot test, or when a test is recorded on a live device. + +## Run a flow from a test + +`Run Flow` runs a Maestro flow for the commands that have no keyword: + +| Form | Example | +|---|---| +| a flow file | `Run Flow ${CURDIR}/flows/onboarding.yaml USER=demo` | +| a directory | `Run Flow ${CURDIR}/flows/ include_tags=smoke exclude_tags=slow` | +| inline YAML | `Run Flow - tapOn:\n text: Next` (a flow without a config section gets the current app's `appId`) | + +- Named arguments become flow environment variables, read in the flow as `${NAME}`. +- `include_tags` and `exclude_tags` select flows by their `tags`, and are only valid with a directory. Pass several tags as a list variable, such as `@{TAGS}`. +- Flow paths in the file resolve next to the file, so `runFlow` and `runScript` calls keep working. + +## Record the commands a test sends + +Import with `record_flows=True`, and every Maestro command the test sends is written to `flows/-.yaml` in the output folder: + +```robotframework +*** Settings *** +Library MaestroLibrary timeout=10s record_flows=True +``` + +Run the test once, then copy the YAML that matches the steps you want to keep. Keep the recording out of version control if it holds credentials. + +## Convert a flow to a Robot test + +The converter needs the `convert` extra (PyYAML): + +```bash +uv add "robotframework-maestrolibrary[convert]" +python -m MaestroLibrary.flow2robot settings_search.yaml > settings_search.robot +``` + +The output is a Robot suite. Review it before use: check each keyword it writes against `robotcode doc keyword MaestroLibrary` and run the suite once. + +## Maestro Studio: record on a live device + +Studio shows the device screen in a window. Each action you take on the screen runs on the device and adds the matching Robot line. + +```bash +uv add "robotframework-maestrolibrary[studio]" # PySide6, PyAV and grpcio +python -m MaestroLibrary.studio --app com.android.settings +``` + +Studio needs the Maestro CLI, adb and scrcpy on the machine, the same as the library. +## Maestro CLI commands + +The library talks to `maestro mcp`. Keyword coverage of the other Maestro subcommands is in the library's `docs/maestro-cli.md`, in the project repository linked from the library's README. diff --git a/plugins/rf-maestro/skills/rf-maestro/references/gestures-and-input.md b/plugins/rf-maestro/skills/rf-maestro/references/gestures-and-input.md new file mode 100644 index 0000000..eaa7c90 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/references/gestures-and-input.md @@ -0,0 +1,60 @@ +# Taps, swipes, scrolling and text input + +Read this when a test taps, swipes, scrolls to an element, types into a field, or hides the keyboard. + +## Taps + +| Keyword | Use | +|---|---| +| `Tap ` | one tap on the element | +| `Tap count=2` | a repeated tap (double tap) | +| `Long Press ` | a long press on the element | +| `Click Element ` | a tap that reads like AppiumLibrary's `Click Element` | +| `Click Text ` | a tap on the element whose text contains the string; `exact_match=True` for the whole text | +| `Click Alert Button