Maestro testing

Maestro Testing

Overview

Use this skill when you need to work on committed Maestro coverage for an app repository. This skill assumes the local machine already has a usable Maestro CLI. If maestro is missing, use $maestro-install first. Treat Maestro as a black-box UI driver: inspect the running device, stabilize selectors, then encode the final behavior in source-controlled YAML under the repo's existing Maestro flow directory.

When to Use

• The user asks to write, review, debug, or run Maestro tests.
• The task involves Maestro Flows, YAML-based UI automation, or Maestro workspace layout.
• The user needs help stabilizing selectors, subflows, or cross-platform end-to-end coverage for iOS, Android, or Web.
• The task mentions Maestro Studio or Maestro CLI workflows tied to app testing.

When Not to Use

• The task is only about installing, updating, repairing, or pinning the Maestro CLI. Use $maestro-install for that.
• The task is about a different automation framework and does not involve Maestro.
• The user wants app instrumentation or internal test harness work rather than UI automation through Maestro.

Inputs to Gather First

• Whether maestro is already available locally with command -v maestro or maestro --version.
• The target app platform and device state.
• The repo's current Maestro flow root, config files, run commands, and naming conventions.
• Existing selector conventions and whether the app already exposes stable accessibility metadata.

Quick Start

• Verify the local CLI exists with command -v maestro or maestro --version. If it is missing, use $maestro-install before continuing.
• Read references/repo/project-discovery.md first to map the target repo's flow directory, workspace config, run commands, env vars, and selector conventions.
• Read references/core/maestro-cli.md for CLI flags, environment variables, and workspace concepts.
• Read references/core/maestro-flow-schema.md when the repo checks in a Maestro schema.json or editor schema wiring and you need exact YAML document, selector, or command shapes.
• Read references/mobile/mobile-patterns.md when the repo is a mobile app and the task involves auth gates, permission dialogs, localization-sensitive selectors, optimistic updates, tags, or Maestro Cloud CI.
• Read references/repo/project-layout.md when the user asks to reorganize Maestro assets or when the repo has no clear structure yet.
• Prefer the repo's existing layout over moving files opportunistically. Only migrate toward the reference layout when the user asks for a refactor or when the current structure is actively blocking maintenance.

Choose the Execution Mode

Interactive exploration

Use available device automation or agent-exposed Maestro tooling when you need to inspect a live device and iterate before committing YAML.

1. List or start a device.
2. Launch the app.
3. Inspect the view hierarchy before guessing selectors.
4. Use focused actions such as tap, input, back, and short ad hoc flows.
5. Capture screenshots when visual confirmation matters.

Rules:

• Inspect first when screen state is uncertain.
• Prefer one or a few commands at a time while debugging.
• Convert stable exploratory steps into committed YAML only after the path works.

Committed flow authoring

Use YAML flows and the Maestro CLI when the scenario should live in source control.

1. Read the nearest existing flow before adding a new one.
2. Reuse subflows with runFlow instead of cloning large blocks.
3. Prefer stable selectors over translated copy.
4. Keep secrets in environment variables, not inline YAML.
5. Run the narrowest possible flow before the whole suite.

Authoring Rules

• Prefer id selectors first.
• Use label when the element exposes a stable accessibility label.
• Use text only when the copy is stable for the active locale.
• Use point only as a last resort and add a short comment explaining why.
• Favor runFlow with when for optional branches.
• Keep conditional branches narrow. If auth, onboarding, or permissions change most of the path, split them into separate runnable flows or dedicated subflows instead of one deeply branched file.
• Favor waitForAnimationToEnd or Maestro's built-in settling over arbitrary sleeps.
• For mobile app repos, wait on a deterministic ready signal before interacting with auth-dependent or data-dependent screens.
• Keep flows isolated. Do not assume execution order unless a workspace config explicitly requires it.
• When the suite grows, use tags and workspace config to control discovery and CI selection instead of encoding environment policy in duplicated flow files.
• If the repo checks in a flow schema, wire it into VS Code for all Maestro workflow files under the project layout's default flow and subflow globs unless the repo already uses different paths or the user asks for an override.
• If app code changes, add or preserve stable accessibility metadata so the flows remain robust.
• Treat new text-based selectors as brittle when the app is localized or copy changes frequently.

Repo Adaptation Workflow

1. Read the nearest AGENTS.md and inspect the existing Maestro files before adding new ones.
2. Identify the current flow root, workspace config, run command, app IDs, env vars, and any checked-in schema or editor wiring. If a schema exists, use references/core/maestro-flow-schema.md to interpret its document and command shapes before editing flows, then make sure VS Code maps that schema across all Maestro workflow files for the repo's default layout or the user's requested override.
3. If the test is brittle because the UI lacks stable selectors, fix the app code first.
4. Keep one clear scenario per flow and move shared steps into subflows instead of cloning blocks.
5. Use environment variables for credentials and secrets. Mirror existing variable names unless the user asks for a broader cleanup.
6. Validate structure with maestro check-syntax or equivalent syntax validation before broad test runs.
7. Run the smallest flow that proves the change, then widen scope only if needed.
8. When reorganizing the suite, use references/repo/project-layout.md as the target shape unless the repo already has a deliberate and well-maintained alternative.

Validation

• The relevant flow passes syntax validation with maestro check-syntax or equivalent validation tooling.
• The smallest flow that proves the change runs successfully before widening scope.
• New or updated selectors rely on stable app metadata where possible.
• Shared logic lives in subflows instead of duplicated command blocks.
• Tag-based or nested-folder suites have config and CLI filters that still match the repo's intended execution model.
• If the repo ships a flow schema, editor settings map it across all intended Maestro workflow globs rather than only one folder or a single file.
• The final flow layout matches the repo's existing conventions unless a deliberate refactor was requested.

Common Failure Modes

• maestro is missing or outdated locally. Use $maestro-install first.
• The UI lacks stable accessibility metadata, forcing brittle text or point-based selectors.
• The flow depends on a device or app state that was never set up explicitly.
• Broad suite runs fail because a small flow was never validated in isolation.
• Sensitive values were embedded inline instead of being passed through environment variables.

Common Command Patterns

maestro test .maestro
maestro test .maestro/flows/smoke/login.yaml
maestro test -c .maestro/flows/smoke/login.yaml
maestro test .maestro --include-tags smoke
maestro test .maestro/flows/smoke/login.yaml -e TEST_EMAIL='[email protected]' -e TEST_PASSWORD='secret'
maestro test .maestro --format JUNIT --output artifacts/maestro/results.xml --test-output-dir artifacts/maestro/test-output --debug-output artifacts/maestro/debug
maestro studio
maestro check-syntax .maestro/flows/smoke/login.yaml

Substitute the repo's actual flow directory and command wrappers when they already exist.

References

• Load references/core/maestro-cli.md when you need official CLI, flow, or environment details.
• Load references/core/maestro-flow-schema.md when a repo ships a checked-in flow schema and you need to understand the exact YAML shapes it validates.
• Load references/mobile/mobile-patterns.md when you need mobile-specific guidance for auth, permissions, conditional subflows, optimistic updates, tags, or Cloud CI.
• Load references/repo/project-discovery.md when you need to map an unfamiliar repo onto Maestro concepts.
• Load references/repo/project-layout.md when you need the proposed reference folder structure for a Maestro suite.