[BUG] openLink fails on iOS simulator: WDA "Unhandled endpoint: /url"

[jongbelegen]

Description

openLink fails on iOS simulators with WDA error: Unhandled endpoint: /url. The bundled WebDriverAgent appears to be missing the /url route handler, so any flow that opens a custom URL scheme (e.g. for Expo dev client deep linking) cannot run.

Steps to Reproduce

1. Install maestro-runner v1.1.13 on macOS arm64.

2. Run maestro-runner wda update (downloads WDA v12.2.0).

3. Run a flow containing openLink against an iOS simulator:

   appId: com.example.app
   ---
   - openLink: my-scheme://some-path

   maestro-runner --platform ios --device <UDID> \
     --app-file /path/to/MyApp.app --no-app-install \
     test flow.yaml

Expected Behavior

The deep link is opened on the simulator (equivalent to xcrun simctl openurl <UDID> "my-scheme://some-path") and execution continues.

Actual Behavior

Step fails immediately:

✗ openLink (0ms)
  ╰─ WDA error: Unhandled endpoint: /url with parameters {
    wildcards =     (
        url
    );
}

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)

Flow File

appId: com.example.app
---
- clearState
- openLink: exp+example://expo-development-client/?url=http%3A%2F%2Flocalhost%3A8111

Error Output

✓ runScript (15ms)
✓ clearState (1.5s)
✗ openLink (0ms)
  ╰─ WDA error: Unhandled endpoint: /url with parameters {
    wildcards =     (
        url
    );
}

Additional Context

maestro CLI runs the same flow successfully against the same simulator, so it's not an environment issue. A simple workaround (bypassing WDA and shelling out to xcrun simctl openurl <udid> <url> for iOS simulators) would unblock this for the simulator case at least; physical devices presumably still need a WDA-side fix.

This blocks adoption for any project using Expo dev client (or other URL-scheme-based launches), where openLink is essential to load the JS bundle from Metro.

[omnarayan]

@jongbelegen thanks for flagging this, we'll dig in and follow up

[omnarayan]

@jongbelegen

Here's what happened: maestro-runner was posting deep links to WDA at POST /session/<sid>/url. That endpoint exists in appium-webdriveragent v11 (which we shipped), but it was moved/removed in v12+. The moment maestro-runner wda update pulled v12.2.0, every openLink step lost its endpoint. Tying our deep-link path to a third-party package's internal routes was the wrong call — especially when we're the ones telling people to run that upgrade.

Fixed in commit 4739a5b by skipping WDA on simulators entirely. xcrun simctl openurl <udid> <url> does the same job without the version coupling, runs in ~100ms instead of going through the WDA HTTP roundtrip, and is also what Maestro CLI does (LocalSimulatorUtils.kt#openURL). Real devices still go through WDA /url since simctl can't reach them.

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