New User Onboarding

The docs are not up to date. I just recently tried to run maestro locally and am really struggling through it.

Might want to revisit how you instruct a first time user how to run locally.

It looks like it is defaulting to android devices for some reason. When one is running, the test will point there, if one isn't running it will fail due to java exceptions related to an emulator not being started.

Why would it be trying to hit an android emulator? This doesn't appear to be configured as part of the start up.

Here is the command I am running:

unzip sample.zip
xcrun simctl install Booted Wikipedia.app
maestro test --debug-output=debug/ ios-flow.yaml

Here is a flattened log:

19:55:56.357 [ INFO] MAESTRO.logSystemInfo: ---- System Info ----
19:55:56.359 [ INFO] MAESTRO.logSystemInfo: Maestro Version: 1.41.0
19:55:56.360 [ INFO] MAESTRO.logSystemInfo: CI: Undefined
19:55:56.360 [ INFO] MAESTRO.logSystemInfo: OS Name: Mac OS X
19:55:56.360 [ INFO] MAESTRO.logSystemInfo: OS Version: 15.6
19:55:56.360 [ INFO] MAESTRO.logSystemInfo: Architecture: aarch64
19:55:56.360 [ INFO] MAESTRO.logSystemInfo: Java Version: 8
19:55:56.545 [ INFO] MAESTRO.logSystemInfo: Xcode Version: 16.4
19:55:56.565 [ INFO] MAESTRO.logSystemInfo: Flutter Version: Undefined
19:55:56.571 [ INFO] MAESTRO.logSystemInfo: Flutter Channel: Undefined
19:55:56.572 [ INFO] MAESTRO.logSystemInfo: ---------------------
19:55:57.479 [ INFO] maestro.cli.command.TestCommand.runShardSuite: [shard 1] Selected device emulator-5554 using port 7001 with execution plan ExecutionPlan(flowsToRun=[/Users/marcusbates/SC/maestro-demo/samples/ios-flow.yaml], sequence=FlowSequence(flows=[], continueOnFailure=true), workspaceConfig=WorkspaceConfig(flows=null, includeTags=null, excludeTags=null, local=null, executionOrder=null, baselineBranch=null, notifications=null, disableRetries=false, platform=PlatformConfiguration(android=AndroidConfiguration(disableAnimations=false), ios=IOSConfiguration(disableAnimations=false, snapshotKeyHonorModalViews=null))))
19:56:01.322 [ INFO] maestro.Maestro.invoke: Getting device info
19:56:01.647 [ INFO] maestro.Maestro.invoke: Got device info: DeviceInfo(platform=ANDROID, widthPixels=1080, heightPixels=2220, widthGrid=1080, heightGrid=2220)
19:56:01.741 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Define variables RUNNING
19:56:01.744 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Define variables metadata CommandMetadata(numberOfRuns=null, evaluatedCommand=MaestroCommand(defineVariablesCommand=DefineVariablesCommand(env={MAESTRO_PROJECT=marcba Digital, MAESTRO_PROJECT_KEY=proj_01k2g68gx5fjq9csembc3kakb0, MAESTRO_KEY=rb_ktknp6cYdWdPX2s7snXoR5PPnxQ3NHM7NJjgWhqNysjVMOk6JgKcAR7NCdmwHyw4aT3kNUR4GUXIkKl6eJYtZz0dBLMdKZXV2DV, MAESTRO_FILENAME=ios-flow}, label=null, optional=false)), logMessages=[], insight=Insight(message=, level=NONE), aiReasoning=null, labeledCommand=null)
19:56:01.747 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Define variables COMPLETED
19:56:01.748 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Apply configuration RUNNING
19:56:01.748 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Apply configuration metadata CommandMetadata(numberOfRuns=null, evaluatedCommand=MaestroCommand(applyConfigurationCommand=ApplyConfigurationCommand(config=MaestroConfig(appId=org.wikimedia.wikipedia, name=null, tags=[ios, passing], ext={}, onFlowStart=null, onFlowComplete=null), label=null, optional=false)), logMessages=[], insight=Insight(message=, level=NONE), aiReasoning=null, labeledCommand=null)
19:56:01.749 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Apply configuration COMPLETED
19:56:01.749 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Launch app "org.wikimedia.wikipedia" RUNNING
19:56:01.749 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Launch app "org.wikimedia.wikipedia" metadata CommandMetadata(numberOfRuns=null, evaluatedCommand=MaestroCommand(launchAppCommand=LaunchAppCommand(appId=org.wikimedia.wikipedia, clearState=null, clearKeychain=null, stopApp=null, permissions=null, launchArguments=null, label=null, optional=false)), logMessages=[], insight=Insight(message=, level=NONE), aiReasoning=null, labeledCommand=null)
19:56:01.803 [ INFO] maestro.Maestro.launchApp: Launching app org.wikimedia.wikipedia
19:56:01.833 [ERROR] maestro.orchestra.Orchestra.executeCommands: [Command execution] CommandFailed: Unable to launch app org.wikimedia.wikipedia: Package org.wikimedia.wikipedia is not installed
19:56:01.834 [ INFO] maestro.Maestro.takeScreenshot: Taking screenshot
19:56:01.835 [TRACE] maestro.utils.ScreenshotUtils.takeScreenshot: Taking screenshot to output sink
19:56:02.561 [ INFO] maestro.cli.runner.MaestroCommandRunner.invoke: Launch app "org.wikimedia.wikipedia" FAILED
19:56:03.141 [ INFO] maestro.drivers.AndroidDriver.close: [Start] close port forwarder
19:56:03.142 [ERROR] maestro.cli.session.MaestroSessionManager.newSession$lambda$0: Failed to record heartbeat
java.lang.InterruptedException: sleep interrupted
	at java.lang.Thread.sleep(Native Method)
	at maestro.cli.session.MaestroSessionManager.newSession$lambda$0(MaestroSessionManager.kt:93)
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
	at java.util.concurrent.FutureTask.runAndReset(FutureTask.java:308)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$301(ScheduledThreadPoolExecutor.java:180)
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:294)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
	at java.lang.Thread.run(Thread.java:750)
19:56:08.150 [ INFO] maestro.drivers.AndroidDriver.close: [Done] close port forwarder
19:56:08.153 [ INFO] maestro.drivers.AndroidDriver.close: [Start] Remove host port from port forwarder map
19:56:08.153 [ INFO] maestro.drivers.AndroidDriver.close: [Done] Remove host port from port forwarder map
19:56:08.153 [ INFO] maestro.drivers.AndroidDriver.close: [Start] Remove host port from port to allocation map
19:56:08.153 [ INFO] maestro.drivers.AndroidDriver.close: [Done] Remove host port from port to allocation map
19:56:08.153 [ INFO] maestro.drivers.AndroidDriver.close: [Start] Uninstall driver from device
19:56:08.899 [ INFO] maestro.drivers.AndroidDriver.close: [Done] Uninstall driver from device
19:56:08.899 [ INFO] maestro.drivers.AndroidDriver.close: [Start] Close instrumentation session
19:56:08.900 [ INFO] maestro.drivers.AndroidDriver.close: [Done] Close instrumentation session
19:56:08.900 [ INFO] maestro.drivers.AndroidDriver.close: [Start] Shutdown GRPC channel
19:56:08.902 [ INFO] maestro.drivers.AndroidDriver.close: [Done] Shutdown GRPC channel

Start by locating the local-run onboarding documentation and reproduce the issue with sample.zip, xcrun simctl, and maestro test --debug-output=debug/ ios-flow.yaml. Done means the instructions explain the required iOS setup and prevent a first-time user from unexpectedly running the flow on an Android emulator.