Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
4 changes: 4 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions .github/ISSUE_TEMPLATE/plugin-feedback.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ body:
- rf-api
- rf-core
- rf-desktop
- rf-maestro
- rf-mind
- rf-mobile
- rf-web
# plugins:end
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

Expand All @@ -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 |
<!-- catalog:end -->
Expand Down
30 changes: 30 additions & 0 deletions docs/catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |

Expand All @@ -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 |

Expand Down Expand Up @@ -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.
Expand Down
23 changes: 23 additions & 0 deletions plugins/rf-maestro/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
28 changes: 28 additions & 0 deletions plugins/rf-maestro/README.md
Original file line number Diff line number Diff line change
@@ -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.
16 changes: 16 additions & 0 deletions plugins/rf-maestro/catalog.yaml
Original file line number Diff line number Diff line change
@@ -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
113 changes: 113 additions & 0 deletions plugins/rf-maestro/skills/rf-maestro/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 <locator> visible` (also `not visible`, `enabled`, `disabled`); `Expect Text <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 <locator>`, `Tap <locator> count=2`, `Long Press <locator>` | `references/gestures-and-input.md` |
| Swipe or scroll | `Swipe start_x=... start_y=... end_x=... end_y=...`, `Swipe By Percent`, `Scroll Down <locator>` | `references/gestures-and-input.md` |
| Type, clear, hide the keyboard | `Input Text <locator> <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 "<Keyword>"`; find names with `robotcode doc keywords MaestroLibrary "<text>"`. 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 <changed files>` (through the project environment, e.g. `uv run robotcode ...`). Fix every error it reports.
4. Run them by longname: `robotcode robot -bl "<Suite.Sub.Test>"` (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 "<longname>"`. 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.
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading