maestro-run

maestro-run - Smart Maestro Test Runner

Run Maestro E2E flows against iOS Simulator with automatic project discovery, category detection, and structured output. Works with any mobile project (Expo, React Native, native Swift/Kotlin, Flutter, etc.).

Usage

/maestro-run                    # Run all flows
/maestro-run smoke              # Category by name
/maestro-run auth               # Another category
/maestro-run <flow-file>        # Specific flow file
/maestro-run studio             # Open Maestro Studio (interactive)

Step 1: Project Discovery

Maestro doesn't enforce a single convention for where flows live. Scan the project to find the right paths — the goal is zero configuration from the user.

# Find .maestro directories (could be at root, in an app subdir, etc.)
find . -name ".maestro" -type d -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null

# If multiple .maestro dirs found, prefer the one closest to cwd
# If none found, check for maestro/ (without dot) or flows/ at root

# Find config file
# Look for: .maestro/config.yaml, .maestro/config.yml, maestro.yaml

Extract from the discovered structure:

What	How	Fallback
Flows dir	<maestro-dir>/flows/ or <maestro-dir>/ if flows are at root level	Ask user
App bundle ID	Parse from config.yaml (appId), or app.json/app.config.js (Expo), or *.xcodeproj (native iOS)	Ask user
Shared sub-flows	<maestro-dir>/shared/ or any _shared//common/ directory	None needed
Categories	Subdirectories inside flows dir (each subdir = one category)	Treat all flows as uncategorized

Important: Do NOT hardcode category names. Discover them dynamically:

# List categories (subdirectories of flows dir)
ls -d <flows-dir>/*/ 2>/dev/null | xargs -I{} basename {}

# List all flow files
find <flows-dir> -name "*.yaml" -o -name "*.yml" | grep -v shared | grep -v _shared | grep -v common