Maestro Mobile Testing Skill for Claude Code / AI Agents

[tovimx]

Maestro Mobile Testing — Agent Skill for Claude Code

Hey Maestro community! 👋

I built a Maestro-focused agent skill that gives AI coding assistants (Claude Code, and any agent supporting the open skills format) deep knowledge of Maestro patterns and best practices for mobile E2E testing.

What is it?

An installable skill that teaches AI agents how to write correct Maestro tests — covering patterns that LLMs frequently get wrong out of the box:

• GraalJS constraints — no async/await, no fetch(), use http.get() and json() instead
• clearState does NOT clear iOS Keychain — expo-secure-store tokens persist across resets
• Auth pre-flight patterns — zero-size marker elements + extendedWaitUntil to avoid race conditions
• Adaptive test flows — when: conditions for guest vs authenticated states
• Optimistic update verification — short timeouts (3s) to catch UI regressions
• OTP testing patterns — digit-by-digit input for split OTP fields
• testID naming conventions — {domain}-{element} and {domain}-{element}-{id} patterns
• CI/CD integration — GitHub Actions with mobile-dev-inc/action-maestro-cloud@v2
• Maestro Cloud — real device testing setup
• Cross-platform gotchas — iOS XCTest crashes, Android cold boot, permission dialogs

Install

npx skills add tovimx/maestro-mobile-testing-skill -y

Repository

🔗 github.com/tovimx/maestro-mobile-testing-skill

Why?

Maestro has great docs, but AI coding assistants don't always know the nuances — they'll generate async/await in GraalJS scripts, miss the Keychain gotcha, or write flaky tests without proper extendedWaitUntil. This skill front-loads all those patterns so the AI gets it right the first time.

Works with any React Native / Expo app. The skill is framework-agnostic — it covers Maestro patterns, not app-specific logic.

Feedback welcome!

This is the first Maestro-specific skill in the ecosystem (there are equivalents for Playwright and Cypress). Would love feedback from the community on what patterns to add or improve.

Thanks for building such a great testing framework! 🎉

[Fishbowler]

This looks ace! 🎉

My first bit of feedback would be to soften some of the more opinionated bits that work for your project, but might not fit all contexts.

e.g. Use IDs if there are translations AND they're available AND ask the user first if they prefer it over test duplication. Typically, folks fluent in Maestro who arent doing i18n go in the other direction, and optimise for text labels, which creates human-readable tests, which makes for maintainable tests (although the latter may be less important for Agent-maintained tests).

Secondly, I'd consider evolving on some of the useful patterns that exist.

e.g. Consider some of the recipes in the docs, highlighting that enabled: true on a selector for a button is useful, and relative position selectors are useful for idiomatically distinguishing between similar elements (e.g. I don't want the second "Add to Basket" button - I want the "Add to Basket" button that belongs to "Awesome Shoes")

[tovimx]

Thanks @Fishbowler, really appreciate the feedback!

Just shipped v1.1.0 addressing both points:

1. Softened the selector stance — Pattern 1 is now "Selector Strategy: testID vs Text" with a context-dependent decision table:

Context	Recommended	Rationale
Multi-language / i18n	id: (testID)	Stable across translations
Single language	Text labels	Human-readable, self-documenting
Agent-maintained	Either — ask the developer	Readability matters less for AI flows
System dialogs	Text (always)	No testID possible on native alerts

The original "always use testIDs, never text" was too opinionated — you're right that single-language projects benefit from text selectors for readability.

2. Added idiomatic patterns from the docs:

• Pattern 10: Selector State Properties — enabled, checked, selected, focused with use-case table and YAML examples
• Pattern 11: Relative Position Selectors — below:, above:, childOf:, containsChild:, containsDescendants:, leftOf:, rightOf: with the "Awesome Shoes" anti-pattern you mentioned

Also updated the new-test checklist to reference all three patterns.

Commit: tovimx/maestro-mobile-testing-skill@d4c0be2