@balazsbarta/mp-skills 0.1.0

package/.agents/skills/maestro/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: maestro
+description: "Maestro mobile testing guide. Covers flow authoring, assertions and commands, EAS CI integration, and common errors. Use this skill when writing or debugging Maestro E2E tests for mobile applications."
+license: MIT
+metadata:
+  author: Balazs Barta
+  version: "2.0.0"
+  repository: https://github.com/balazsbarta/mp-skills
+  tags:
+    - maestro
+    - mobile-testing
+    - e2e
+    - ios
+    - android
+---
+
+# Maestro Guide
+
+Write end-to-end mobile tests with Maestro.
+
+## ⚠️ Critical: Do not trust internal knowledge
+
+**Everything you know about Maestro may be outdated or wrong. Never rely on memory. Always verify against current documentation.**
+
+Maestro commands, assertions, and CI integrations evolve. Always check the references in this skill for current syntax.
+
+## Prerequisites
+
+**Before writing tests**, verify Maestro is installed:
+
+```bash
+maestro --version
+```
+
+If not installed:
+
+```bash
+# macOS
+curl -Ls "https://get.maestro.mobile.dev" | bash
+
+# Or via Homebrew
+brew tap mobile-dev-inc/tap
+brew install maestro
+```
+
+Ensure a simulator/emulator is running:
+
+```bash
+# iOS simulator
+xcrun simctl list devices | grep Booted
+
+# Android emulator
+adb devices
+```
+
+## Documentation lookup guide
+
+### Quick reference
+
+| User Question | First Check | How To |
+| --- | --- | --- |
+| "How do I write a test flow?" | [`references/flow-authoring.md`](references/flow-authoring.md) | YAML syntax, tap/scroll/input commands |
+| "What assertions are available?" | [`references/assertions-commands.md`](references/assertions-commands.md) | Visibility, text, and state assertions |
+| "How do I run in CI with EAS?" | [`references/eas-ci-integration.md`](references/eas-ci-integration.md) | EAS Build + Maestro Cloud setup |
+| "I'm getting an error..." | [`references/common-errors.md`](references/common-errors.md) | Common errors and solutions |
+| "I need canonical command syntax" | [`references/remote-docs.md`](references/remote-docs.md) | Verify with official Maestro docs |
+
+### Priority order for writing tests
+
+1. **Local environment checks first**
+
+   - Verify CLI version and active device/emulator.
+   - Confirm app identifiers in local project config.
+
+2. **Local skill references second**
+
+   - Use flow/assertions/CI/common-errors references in this skill.
+
+3. **Official docs third**
+
+   - Use `references/remote-docs.md` for canonical command behavior.
+
+## Core concepts
+
+### Flow structure
+
+A Maestro flow is a YAML file with sequential commands:
+
+```yaml
+# flows/login.yaml
+appId: com.example.myapp
+---
+- launchApp
+- tapOn: "Log in"
+- tapOn: "Email"
+- inputText: "user@example.com"
+- tapOn: "Password"
+- inputText: "password123"
+- tapOn: "Submit"
+- assertVisible: "Dashboard"
+```
+
+### Key commands
+
+| Command | Purpose | Example |
+| --- | --- | --- |
+| `tapOn` | Tap an element | `tapOn: "Submit"` |
+| `inputText` | Type text | `inputText: "hello"` |
+| `assertVisible` | Assert element visible | `assertVisible: "Welcome"` |
+| `assertNotVisible` | Assert element hidden | `assertNotVisible: "Loading"` |
+| `scrollUntilVisible` | Scroll to find element | `scrollUntilVisible: { element: "Item 50" }` |
+| `swipe` | Swipe gesture | `swipe: { direction: "LEFT" }` |
+| `back` | Press back button | `back` |
+| `waitForAnimationToEnd` | Wait for animations | `waitForAnimationToEnd` |
+
+### Element selection
+
+Maestro finds elements by:
+1. **Text content** — `tapOn: "Submit"` matches visible text
+2. **Accessibility ID** — `tapOn: { id: "submit-button" }` matches `testID`/`accessibilityIdentifier`
+3. **Index** — `tapOn: { text: "Item", index: 0 }` for multiple matches
+
+## Critical requirements
+
+### Set testID on elements
+
+For reliable tests, add `testID` to interactive elements:
+
+```tsx
+// React Native
+<TouchableOpacity testID="submit-button">
+  <Text>Submit</Text>
+</TouchableOpacity>
+```
+
+### appId must match
+
+The `appId` in the flow must match the app's bundle identifier:
+- iOS: `bundleIdentifier` in `app.json`
+- Android: `package` in `app.json`
+
+## When you see errors
+
+**Most Maestro failures are selector/device/app-id mismatches.**
+
+1. Verify `appId` and running device state.
+2. Prefer stable selectors (`id`) over text where possible.
+3. Confirm command syntax in `references/remote-docs.md`.
+
+## Step-by-step workflow
+
+### 1. Create flows directory
+
+```bash
+mkdir -p .maestro/flows
+```
+
+### 2. Write a flow
+
+```yaml
+# .maestro/flows/login.yaml
+appId: com.example.myapp
+---
+- launchApp
+- tapOn: "Log in"
+- tapOn: { id: "email-input" }
+- inputText: "user@example.com"
+- tapOn: { id: "password-input" }
+- inputText: "password123"
+- tapOn: { id: "submit-button" }
+- assertVisible: "Dashboard"
+```
+
+### 3. Run the flow
+
+```bash
+maestro test .maestro/flows/login.yaml
+```
+
+### 4. Run all flows
+
+```bash
+maestro test .maestro/flows/
+```
+
+### 5. Record (interactive mode)
+
+```bash
+maestro studio
+```
+
+## Error handling
+
+### Common issues
+
+| Symptom | Likely Cause | Fix |
+| --- | --- | --- |
+| "Element not found" | Wrong text or testID | Use `maestro studio` to inspect elements |
+| "App not installed" | Wrong appId or app not on device | Check `appId`, install app first |
+| "Timeout" | Element takes too long to appear | Add `waitForAnimationToEnd` or increase timeout |
+| "No device found" | No simulator/emulator running | Start a simulator or connect a device |
+
+## Expected outputs
+
+```bash
+# Successful test run
+Running flow: login.yaml
+  ✓ launchApp
+  ✓ tapOn: "Log in"
+  ✓ tapOn: { id: "email-input" }
+  ✓ inputText: "user@example.com"
+  ✓ tapOn: { id: "password-input" }
+  ✓ inputText: "password123"
+  ✓ tapOn: { id: "submit-button" }
+  ✓ assertVisible: "Dashboard"
+
+Flow completed successfully
+```
+
+## Cross-references
+
+- **React Native Expo**: [../react-native-expo/SKILL.md](../react-native-expo/SKILL.md) — Building the mobile apps that Maestro tests
+
+## Resources
+
+- **Flow authoring**: [`references/flow-authoring.md`](references/flow-authoring.md)
+- **Assertions and commands**: [`references/assertions-commands.md`](references/assertions-commands.md)
+- **EAS CI integration**: [`references/eas-ci-integration.md`](references/eas-ci-integration.md)
+- **Common errors**: [`references/common-errors.md`](references/common-errors.md)
+- **Official docs lookup**: [`references/remote-docs.md`](references/remote-docs.md)

package/.agents/skills/maestro/references/assertions-commands.md

@@ -0,0 +1,259 @@
+# Assertions and Commands
+
+Complete reference for Maestro assertions and commands.
+
+## When to use this reference
+
+- Looking up available assertion types
+- Understanding command syntax
+- Combining assertions for complex validations
+
+## Visibility assertions
+
+### Assert element is visible
+
+```yaml
+- assertVisible: "Welcome"
+- assertVisible: { id: "header" }
+- assertVisible:
+    text: "Welcome"
+    enabled: true
+```
+
+### Assert element is NOT visible
+
+```yaml
+- assertNotVisible: "Loading"
+- assertNotVisible: { id: "spinner" }
+```
+
+### Wait until visible
+
+```yaml
+- extendedWaitUntil:
+    visible: "Dashboard"
+    timeout: 10000
+```
+
+### Wait until NOT visible
+
+```yaml
+- extendedWaitUntil:
+    notVisible: "Loading..."
+    timeout: 10000
+```
+
+## Text assertions
+
+### Assert contains text
+
+```yaml
+- assertVisible: "Welcome, Alice"
+
+# Regex match
+- assertVisible: "Welcome, .*"
+```
+
+### Assert text in specific element
+
+```yaml
+- assertVisible:
+    id: "balance-display"
+    text: "$100.00"
+```
+
+## State assertions
+
+### Element is enabled/disabled
+
+```yaml
+- assertVisible:
+    text: "Submit"
+    enabled: true
+
+- assertVisible:
+    text: "Submit"
+    enabled: false
+```
+
+### Element is checked (checkboxes)
+
+```yaml
+- assertVisible:
+    id: "agree-checkbox"
+    checked: true
+```
+
+### Element is selected
+
+```yaml
+- assertVisible:
+    id: "tab-home"
+    selected: true
+```
+
+## Tap commands
+
+### Simple tap
+
+```yaml
+- tapOn: "Button Text"
+- tapOn: { id: "my-button" }
+```
+
+### Tap with options
+
+```yaml
+- tapOn:
+    text: "Submit"
+    retryTapIfNoChange: true    # Retry if screen doesn't change
+    longPress: true             # Long press
+
+- tapOn:
+    point: "50%, 80%"          # Tap by coordinates (percentage)
+```
+
+### Double tap
+
+```yaml
+- doubleTapOn: "Image"
+- doubleTapOn: { id: "zoomable-image" }
+```
+
+## Scroll commands
+
+### Basic scroll
+
+```yaml
+- scroll                       # Scroll down (default)
+- scroll:
+    direction: "UP"
+```
+
+### Scroll until visible
+
+```yaml
+- scrollUntilVisible:
+    element: "Load More"
+    direction: "DOWN"
+    timeout: 30000
+    speed: 40                  # Scroll speed (0-100)
+```
+
+## Swipe commands
+
+```yaml
+# Directional swipe
+- swipe:
+    direction: "LEFT"
+    duration: 500
+
+# Coordinate-based swipe
+- swipe:
+    start: "90%, 50%"
+    end: "10%, 50%"
+    duration: 500
+```
+
+## Input commands
+
+```yaml
+- inputText: "Hello World"
+- clearText
+- clearText: { id: "search-input" }
+- pressKey: "Enter"
+- pressKey: "Backspace"
+- hideKeyboard
+```
+
+## Navigation commands
+
+```yaml
+- launchApp
+- launchApp:
+    clearState: true
+    clearKeychain: true
+
+- stopApp
+- stopApp: { appId: "com.example.myapp" }
+
+- back                         # System back button
+- openLink: "myapp://profile"  # Deep link
+```
+
+## Wait commands
+
+```yaml
+- waitForAnimationToEnd
+- waitForAnimationToEnd:
+    timeout: 5000
+
+- extendedWaitUntil:
+    visible: "Content"
+    timeout: 15000
+```
+
+## Screenshot and recording
+
+```yaml
+- takeScreenshot: "step-name"
+# Output: .maestro/screenshots/step-name.png
+
+- startRecording: "test-recording"
+# ... commands ...
+- stopRecording
+```
+
+## Device commands
+
+```yaml
+# Set location (simulator only)
+- setLocation:
+    latitude: 37.7749
+    longitude: -122.4194
+
+# Toggle airplane mode (Android only)
+- toggleAirplaneMode
+```
+
+## Conditional execution
+
+```yaml
+- runFlow:
+    when:
+      visible: "Accept Cookies"
+    commands:
+      - tapOn: "Accept"
+```
+
+## Repeat
+
+```yaml
+- repeat:
+    times: 5
+    commands:
+      - tapOn: "Next"
+```
+
+## Assertion command summary
+
+| Command | Purpose |
+| --- | --- |
+| `assertVisible` | Element is on screen |
+| `assertNotVisible` | Element is not on screen |
+| `extendedWaitUntil` | Wait for visibility/invisibility |
+| `assertTrue` | Custom JavaScript condition |
+
+## Troubleshooting
+
+### Assertion timing out
+
+- Add `waitForAnimationToEnd` before assertion
+- Increase timeout: `timeout: 30000`
+- Use `maestro studio` to verify element is actually visible
+
+### Wrong element matched
+
+- Use `id` selector for precision
+- Add `index` for multiple matches
+- Use `below`/`above` for relative positioning