diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b47ef84..25954e2 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -108,6 +108,51 @@ "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-mind", + "source": "./plugins/rf-mind", + "description": "robotframework-mind skill for exact lookups in a Robot Framework test repo: tickets, keywords, callers, tags and endpoints.", + "author": { + "name": "ai94iq" + }, + "homepage": "https://github.com/MarketSquare/robotframework-plugins", + "repository": "https://github.com/MarketSquare/robotframework-plugins", + "license": "Apache-2.0", + "keywords": [ + "robotframework", + "testing", + "code-search", + "ticket", + "keyword" + ], + "category": "testing", + "tags": [ + "robot-framework", + "community" + ] + }, { "name": "rf-mobile", "source": "./plugins/rf-mobile", diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 15cc426..10ef0c0 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -28,6 +28,10 @@ /plugins/rf-desktop/ @manykarim @MarketSquare/robotframework-plugins-reviewers /plugins/rf-desktop/skills/rf-platynui/ @manykarim @MarketSquare/robotframework-plugins-reviewers /plugins/rf-desktop/.claude-plugin/ @manykarim @MarketSquare/robotframework-plugins-reviewers @MarketSquare/robotframework-plugins-security +/plugins/rf-maestro/ @ai94iq +/plugins/rf-maestro/.claude-plugin/ @ai94iq @MarketSquare/robotframework-plugins-security +/plugins/rf-mind/ @ai94iq +/plugins/rf-mind/.claude-plugin/ @ai94iq @MarketSquare/robotframework-plugins-security /plugins/rf-mobile/ @manykarim @MarketSquare/robotframework-plugins-reviewers /plugins/rf-mobile/skills/rf-appium/ @manykarim @MarketSquare/robotframework-plugins-reviewers /plugins/rf-mobile/.claude-plugin/ @manykarim @MarketSquare/robotframework-plugins-reviewers @MarketSquare/robotframework-plugins-security diff --git a/.github/ISSUE_TEMPLATE/plugin-feedback.yml b/.github/ISSUE_TEMPLATE/plugin-feedback.yml index 056357b..51a44b6 100644 --- a/.github/ISSUE_TEMPLATE/plugin-feedback.yml +++ b/.github/ISSUE_TEMPLATE/plugin-feedback.yml @@ -20,6 +20,8 @@ body: - rf-api - rf-core - rf-desktop + - rf-maestro + - rf-mind - rf-mobile - rf-web # plugins:end diff --git a/README.md b/README.md index 7ef4e22..0400c70 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Install `rf-core` for the Robot Framework language, environment setup and Python | `rf-api` | 1.0.0 | verified | active | RequestsLibrary and RESTinstance skills for API tests. | RequestsLibrary, RESTinstance | [@manykarim](https://github.com/manykarim) | | `rf-core` | 1.0.0 | 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-desktop` | 1.0.0 | verified | active | PlatynUI skill for desktop UI tests. | PlatynUI | [@manykarim](https://github.com/manykarim) | +| `rf-maestro` | 1.0.0 | community | active | MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. | MaestroLibrary | [@ai94iq](https://github.com/ai94iq) | +| `rf-mind` | 1.0.0 | community | active | robotframework-mind skill for exact lookups in a Robot Framework test repo: tickets, keywords, callers, tags and endpoints. | Robot Framework | [@ai94iq](https://github.com/ai94iq) | | `rf-mobile` | 1.0.0 | verified | active | AppiumLibrary skill for Android and iOS tests. | AppiumLibrary | [@manykarim](https://github.com/manykarim) | | `rf-web` | 1.0.0 | verified | active | Browser Library and SeleniumLibrary skills for web tests. | Browser, SeleniumLibrary | [@manykarim](https://github.com/manykarim) | @@ -28,6 +30,8 @@ The Python installer bundles these plugin versions: | `rf-api` | 1.0.0 | verified | | `rf-core` | 1.0.0 | verified | | `rf-desktop` | 1.0.0 | verified | +| `rf-maestro` | 1.0.0 | community | +| `rf-mind` | 1.0.0 | community | | `rf-mobile` | 1.0.0 | verified | | `rf-web` | 1.0.0 | verified | diff --git a/docs/catalog.md b/docs/catalog.md index 7a753a9..d40b09c 100644 --- a/docs/catalog.md +++ b/docs/catalog.md @@ -8,6 +8,8 @@ | `rf-api` | 1.0.0 | verified | active | RequestsLibrary and RESTinstance skills for API tests. | RequestsLibrary, RESTinstance | [@manykarim](https://github.com/manykarim) | | `rf-core` | 1.0.0 | 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-desktop` | 1.0.0 | verified | active | PlatynUI skill for desktop UI tests. | PlatynUI | [@manykarim](https://github.com/manykarim) | +| `rf-maestro` | 1.0.0 | community | active | MaestroLibrary skill for Android and iOS tests driven by Maestro, with no Appium server. | MaestroLibrary | [@ai94iq](https://github.com/ai94iq) | +| `rf-mind` | 1.0.0 | community | active | robotframework-mind skill for exact lookups in a Robot Framework test repo: tickets, keywords, callers, tags and endpoints. | Robot Framework | [@ai94iq](https://github.com/ai94iq) | | `rf-mobile` | 1.0.0 | verified | active | AppiumLibrary skill for Android and iOS tests. | AppiumLibrary | [@manykarim](https://github.com/manykarim) | | `rf-web` | 1.0.0 | verified | active | Browser Library and SeleniumLibrary skills for web tests. | Browser, SeleniumLibrary | [@manykarim](https://github.com/manykarim) | @@ -21,6 +23,8 @@ | `rf-api` | 1.0.0 | verified | | `rf-core` | 1.0.0 | verified | | `rf-desktop` | 1.0.0 | verified | +| `rf-maestro` | 1.0.0 | community | +| `rf-mind` | 1.0.0 | community | | `rf-mobile` | 1.0.0 | verified | | `rf-web` | 1.0.0 | verified | @@ -77,6 +81,32 @@ 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 +- **Version:** 1.0.0 +- **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-mind + +robotframework-mind skill for exact lookups in a Robot Framework test repo: tickets, keywords, callers, tags and endpoints. + +- **Tier:** community +- **Status:** active +- **Version:** 1.0.0 +- **Robot Framework:** `>=7` +- **Tested with:** claude-code +- **Maintainers:** [@ai94iq](https://github.com/ai94iq) +- **Install (Claude Code):** `/plugin install rf-mind@robotframework-plugins` + ## rf-mobile AppiumLibrary skill for Android and iOS tests. diff --git a/plugins/rf-maestro/.claude-plugin/plugin.json b/plugins/rf-maestro/.claude-plugin/plugin.json new file mode 100644 index 0000000..bede1c3 --- /dev/null +++ b/plugins/rf-maestro/.claude-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "rf-maestro", + "version": "1.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": [ + { + "name": "rf-core", + "version": "^1.0" + } + ] +} 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/skills/rf-maestro/SKILL.md b/plugins/rf-maestro/skills/rf-maestro/SKILL.md new file mode 100644 index 0000000..3e392bf --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/SKILL.md @@ -0,0 +1,113 @@ +--- +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 + version: "1.0.0" +--- + +# 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..70da9b8 --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/references/device-state.md @@ -0,0 +1,53 @@ +# 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 | +| iOS keychain | `Clear Keychain` | iOS simulator | +| 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..680364c --- /dev/null +++ b/plugins/rf-maestro/skills/rf-maestro/references/flows-and-studio.md @@ -0,0 +1,54 @@ +# 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. The release page of the library project also has standalone builds for Windows, Linux and macOS. Those builds are not signed, and the release notes say how to open them. + +## 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