android-maestro

Files (1)

• SKILL.md

SKILL.md (first lines)

# Maestro (UI automation)

## Purpose

Validate real user workflows on device or emulator.

## When to load

UI automation phase after build/unit/integration. Maestro YAML edits.

## Inputs

- FR user flows and acceptance criteria.
- App `appId` from manifest.
- [maestro-runbook.md](../android-orchestrator/references/maestro-runbook.md)

## Outputs

- Create or update flows; run `maestro test <flow.yaml>` or `maestro test <directory>`.

## Rules

### Before the first Maestro run this session

Follow [quality-tooling.md](../android-orchestrator/references/quality-tooling.md). If `maestro` is not on PATH, share the **Maestro CLI** section of [setup-guides.md](../android-orchestrator/references/setup-guides.md) when asking the user. If there is no device or the user skips Maestro, **do not run** `maestro test`; record **Maestro: N/A** and continue.

- [Maestro flows](https://docs.maestro.dev/maestro-flows)
- [Android](https://docs.maestro.dev/get-started/supported-platform/android)
- [Selectors](https://docs.maestro.dev/reference/selectors/core-selectors.md)

**Preferred** UI automation unless technical reason otherwise.

Journey pattern: Launch → Login (if needed) → Navigate → Act → Verify → Back → Verify state.

```yaml
appId: com.example.app
env:
  TEST_USER: ${TEST_USER}  # supply locally; never commit real credentials
---
- launchApp
- runFlow: login.yaml
- tapOn:
    id: book_appointment
- assertVisible: "Confirmed"
```

Use semantic matchers; `testTag` / `id:` when text is ambiguous.

For Jetpack Compose, `id:` matches `Modifier.testTag` only when the app sets `Modifier.semantics { testTagsAsResourceId = true }` high in the UI tree. **Dialogs and date pickers** often render outside the root — apply the same semantics on dialog content, or fall back to stable visible text (e.g. Material **“OK”** on `DatePickerDialog`).

### UI-change gate

When Maestro is **in scope** ([quality-tooling.md](../android-orchestrator/references/quality-tooling.md)), re-run at least one **smoke** flow after a user-facing UI change (with Gradle unit tests). If Maestro is **N/A**, do not run smoke; unit or Compose UI tests cover the change instead. Typical Maestro sequence: install debug APK → `adb shell pm clear <appId>` when the flow assumes empty/first-run state → `maestro test <flow>`.

### Compose flow tips

- Prefer a dedicated `testTag` on the control that opens a picker (e.g. `open_date_picker`), not the read-only field text.
- Empty-list smoke fails if prior runs left data — always clear app data or use a dedicated test account flow.
- When using Maestro MCP, pass an **absolute path** to the flows directory if the tool resolves relative paths from the wrong cwd. Tag filters (`include_tags`) only work when flows declare matching tags.

Do not load database/Compose implementation skills while authoring flows — only FR journey context.

## Dependencies

- `android-testing`
- `android-functional-requirements`

## Validation

- Flow passes locally or blocker documented with runbook fallback (Compose UI tests).

## Anti-patterns

- Maestro loaded during pure repository implementation.
- Marking UI gate done when no device/emulator was available and no fallback tests ran.

From Kapil-SquareNetra/android-agentic-orchestrator, MIT.

More from Kapil-SquareNetra/android-agentic-orchestrator