[BUG] clearState on iOS reinstalls app, requires --app-file (Maestro CLI clears in-place)

[jongbelegen]

Description

clearState on iOS simulators requires the --app-file flag and performs a full uninstall + reinstall of the app. Maestro CLI's clearState clears app data in place without uninstalling, so flows that use clearState for fast per-test resets are not portable to maestro-runner without reconfiguration.

Beyond the configuration burden, the reinstall path is fragile: pointing --app-file at the currently-installed .app inside ~/Library/Developer/CoreSimulator/Devices/<UDID>/data/Containers/Bundle/Application/<UUID>/ fails because the simulator container is removed by the uninstall step before the reinstall step runs (lstat ... failed: No such file or directory). Users must keep a separate copy of the .app (e.g. from DerivedData) just to satisfy the reinstall.

Steps to Reproduce

1. Run a flow containing clearState on an iOS simulator without --app-file:

   maestro-runner --platform ios --device <UDID> test flow.yaml

   appId: com.example.app
   ---
   - clearState

2. The same flow runs cleanly under maestro CLI with no extra config.

Expected Behavior

Either:

• clearState clears app data in place (matching Maestro CLI behavior — no --app-file required), or
• The reinstall path is robust to the case where --app-file points at the live simulator-container path (resolve and cache the .app before uninstall).

A documented option flag (e.g. --clear-state-mode=data|reinstall) would also resolve this.

Actual Behavior

Without --app-file:

✗ clearState (1.0s)
  ╰─ clearState on iOS requires --app-file for reinstall
Usage: maestro-runner --app-file <path-to-ipa-or-app> --platform ios test <flow-files>

With --app-file pointing at the live simulator-container path:

✗ clearState (2.0s)
  ╰─ simctl install failed: exit status 2: An error was encountered processing the command (domain=NSPOSIXErrorDomain, code=2):
Simulator device failed to install the application.
Underlying error (domain=NSPOSIXErrorDomain, code=2):
	lstat of /Users/.../CoreSimulator/Devices/<UDID>/data/Containers/Bundle/Application/<UUID>/MyApp.app failed: No such file or directory

(The path is valid before clearState runs; uninstall removes the container, then the reinstall fails.)

With --app-file pointing at a DerivedData .app: works, but adds 1.5–3s per clearState and requires the user to track a separate .app path outside the simulator.

Environment

• OS: macOS 15.0 (Darwin 24.6.0)
• maestro-runner version: 1.1.13 (commit 7addd21)
• WDA version: 12.2.0
• Executor: Native (default WDA driver)
• Device/Simulator: iPhone 16, iOS 18.6 (Simulator)

Additional Context

For projects with many shared setup flows that all call clearState (e.g. Expo apps with per-test seed scripts), this turns "drop in and go" into a meaningful porting effort. The two practical paths today are:

1. Keep a built .app outside the simulator and pass --app-file everywhere.
2. Rewrite shared setup flows to drop clearState and reset state via the backend instead.

A clear-in-place implementation (matching Maestro CLI) would be a much easier migration path.

[omnarayan]

@jongbelegen Thanks for the detailed write-up

Why it works this way today

When I first added clearState for iOS, I borrowed the uninstall + reinstall approach from Maestro CLI but didn't copy the full thing. Maestro CLI also reinstalls (iOS doesn't give you a way to wipe just the data container), but before uninstalling it auto-discovers the installed .app via xcrun simctl get_app_container <udid> <bundleId> and stages a copy in a temp dir first. The reinstall then runs from the staged copy — that's why their flow doesn't need --app-file.

I skipped the staging step initially, assuming requiring --app-file was a fine tradeoff. It isn't — especially for projects with shared setup flows or per-test seeds where every flow ends up carrying the flag. And you're right that pointing --app-file at the live simulator container path is a trap: the uninstall wipes that path before install can read it, hence the lstat ... No such file or directory.

The fix

Patching clearAppStateSimulator to mirror Maestro CLI's behavior:

1. No --app-file → run simctl get_app_container to find the installed .app, copy to a temp dir, uninstall, install from temp, clean up.
2. --app-file points inside /CoreSimulator/Devices/<udid>/ → detect the live-container case and stage anyway. No more lstat failure.
3. --app-file points to an external path (e.g. DerivedData) → unchanged.

A couple of details worth calling out:

• Speed: the staging copy uses cp -c (APFS clone-on-write). Both the sim container and /var/folders/.../Tn/... (where os.MkdirTemp lands) are APFS on the same volume on every Mac, so the clone is basically free — nothing actually gets copied until something writes to the file, which we never do. Cost vs the current working path: roughly 0 ms regardless of app size. Should actually be a bit faster than Maestro CLI, which uses a regular copy.
• Better error on real devices: simctl get_app_container doesn't work for real iOS devices (the .app is sealed, no public API to pull it back — Maestro CLI hits the same wall). Real devices will still need --app-file, but with a clearer message: "clearState on real iOS devices requires --app-file — the installed bundle isn't reachable from the host. On simulators no flag is needed."

Scope

• ✅ iOS Simulator: no more --app-file requirement, auto-staged, fast, drop-in compatible with Maestro CLI flows.
• ⚪ iOS Real Device: still requires --app-file (Apple's restriction, not ours), but with a clearer error.

[omnarayan]

@jongbelegen

Pre-release build is up — would appreciate a try before we ship 1.1.14:

curl -fsSL https://open.devicelab.dev/install/maestro-runner | bash -s -- --version 1.1.14-rc1