fix: warn when multiple simulators are booted (#94)

`get_booted_device_udid()` silently returned the first booted simulator.
When more than one is booted (or a stale idb companion lingers), gesture
and tap commands resolve to a device other than the one being watched —
idb reports success on the wrong device, so swipes/scrolls silently no-op
with no error.

Keep the first-match default but print a stderr warning on ambiguity
naming the selected device and advising an explicit --udid. Add
`get_booted_device_udids()` so callers can detect the multi-device case,
plus regression tests covering single/multiple/none/failure listings.

Author: conorluddy

ios-simulator-skill/skills/ios-simulator-skill/scripts/common/__init__.py

@@ -16,6 +16,7 @@
     build_idb_command,
     build_simctl_command,
     get_booted_device_udid,
+    get_booted_device_udids,
     get_device_screen_size,
     resolve_udid,
     transform_screenshot_coords,
@@ -49,6 +50,7 @@
     "generate_screenshot_name",
     "get_accessibility_tree",
     "get_booted_device_udid",
+    "get_booted_device_udids",
     "get_cache",
     "get_device_screen_size",
     "get_screen_size",

ios-simulator-skill/skills/ios-simulator-skill/scripts/common/device_utils.py

@@ -17,6 +17,7 @@
 import json
 import re
 import subprocess
+import sys
 
 
 def build_simctl_command(
@@ -121,21 +122,20 @@ def build_idb_command(
     return cmd
 
 
-def get_booted_device_udid() -> str | None:
+def get_booted_device_udids() -> list[str]:
     """
-    Auto-detect currently booted simulator UDID.
+    List the UDIDs of every currently booted simulator.
 
-    Queries xcrun simctl for booted devices and returns first match.
+    Queries `xcrun simctl list devices booted` and extracts each UDID in the
+    order reported.
 
     Returns:
-        UDID of booted simulator, or None if no simulator is booted.
+        UDIDs of all booted simulators, or an empty list if none are booted
+        (or the query fails).
 
     Example:
-        udid = get_booted_device_udid()
-        if udid:
-            print(f"Booted simulator: {udid}")
-        else:
-            print("No simulator is currently booted")
+        udids = get_booted_device_udids()
+        # ["ABC123-...", "DEF456-..."] when two simulators are running
     """
     try:
         result = subprocess.run(
@@ -144,18 +144,48 @@ def get_booted_device_udid() -> str | None:
             text=True,
             check=True,
         )
+    except subprocess.CalledProcessError:
+        return []
 
-        # Parse output to find UDID
-        # Format: "  iPhone 16 Pro (ABC123-DEF456) (Booted)"
-        for line in result.stdout.split("\n"):
-            # Look for UUID pattern in parentheses
-            match = re.search(r"\(([A-F0-9\-]{36})\)", line)
-            if match:
-                return match.group(1)
+    # Format: "  iPhone 16 Pro (ABC123-DEF456) (Booted)"
+    udids: list[str] = []
+    for line in result.stdout.split("\n"):
+        match = re.search(r"\(([A-F0-9\-]{36})\)", line)
+        if match:
+            udids.append(match.group(1))
+    return udids
 
+
+def get_booted_device_udid() -> str | None:
+    """
+    Auto-detect a booted simulator UDID.
+
+    Returns the first booted simulator. When more than one simulator is booted
+    the choice is ambiguous — gesture/tap commands can silently target a device
+    other than the one you are watching (idb reports success on the wrong
+    device, so nothing appears to happen). In that case a warning is printed to
+    stderr naming the selected device and advising an explicit ``--udid``.
+
+    Returns:
+        UDID of a booted simulator, or None if no simulator is booted.
+
+    Example:
+        udid = get_booted_device_udid()
+        if udid:
+            print(f"Booted simulator: {udid}")
+        else:
+            print("No simulator is currently booted")
+    """
+    udids = get_booted_device_udids()
+    if not udids:
         return None
-    except subprocess.CalledProcessError:
-        return None
+    if len(udids) > 1:
+        print(
+            f"Warning: {len(udids)} booted simulators detected ({', '.join(udids)}). "
+            f"Auto-selecting {udids[0]} — pass --udid to target a specific device.",
+            file=sys.stderr,
+        )
+    return udids[0]
 
 
 def resolve_udid(udid_arg: str | None) -> str:

tests/test_booted_device_selection.py

@@ -0,0 +1,83 @@
+"""Regression tests for ambiguous booted-device auto-selection.
+
+When more than one simulator is booted, `get_booted_device_udid()` used to
+silently return the first match. Gesture/tap commands resolve their target via
+this helper, so they could land on a simulator other than the one being watched
+(idb reports success on the wrong device, so nothing appears to happen). The fix
+keeps the first-match behaviour but emits a stderr warning on ambiguity, and
+exposes `get_booted_device_udids()` so callers can detect the multi-device case.
+"""
+
+import subprocess
+
+import pytest
+from common.device_utils import get_booted_device_udid, get_booted_device_udids
+
+UDID_A = "AAAAAAAA-1111-2222-3333-444444444444"
+UDID_B = "BBBBBBBB-5555-6666-7777-888888888888"
+
+
+def _fake_simctl(stdout: str):
+    """Return a subprocess.run stub that yields the given booted-device listing."""
+
+    def _run(*_args, **_kwargs):
+        return subprocess.CompletedProcess(args=[], returncode=0, stdout=stdout, stderr="")
+
+    return _run
+
+
+# === get_booted_device_udids ===
+
+
+def test_lists_all_booted_udids(monkeypatch):
+    listing = (
+        f"-- iOS 26.2 --\n"
+        f"    iPhone 17 Pro ({UDID_A}) (Booted)\n"
+        f"    iPad Pro ({UDID_B}) (Booted)\n"
+    )
+    monkeypatch.setattr(subprocess, "run", _fake_simctl(listing))
+    assert get_booted_device_udids() == [UDID_A, UDID_B]
+
+
+def test_returns_empty_when_none_booted(monkeypatch):
+    monkeypatch.setattr(subprocess, "run", _fake_simctl("== Devices ==\n-- iOS 26.2 --\n"))
+    assert get_booted_device_udids() == []
+
+
+def test_returns_empty_when_simctl_fails(monkeypatch):
+    def _boom(*_args, **_kwargs):
+        raise subprocess.CalledProcessError(1, "simctl")
+
+    monkeypatch.setattr(subprocess, "run", _boom)
+    assert get_booted_device_udids() == []
+
+
+# === get_booted_device_udid ===
+
+
+def test_single_device_returns_udid_without_warning(monkeypatch, capsys):
+    listing = f"-- iOS 26.2 --\n    iPhone 17 Pro ({UDID_A}) (Booted)\n"
+    monkeypatch.setattr(subprocess, "run", _fake_simctl(listing))
+
+    assert get_booted_device_udid() == UDID_A
+    assert capsys.readouterr().err == ""
+
+
+def test_multiple_devices_warns_and_picks_first(monkeypatch, capsys):
+    listing = f"    iPhone 17 Pro ({UDID_A}) (Booted)\n    iPad Pro ({UDID_B}) (Booted)\n"
+    monkeypatch.setattr(subprocess, "run", _fake_simctl(listing))
+
+    assert get_booted_device_udid() == UDID_A
+    stderr = capsys.readouterr().err
+    assert "2 booted simulators" in stderr
+    assert UDID_A in stderr and UDID_B in stderr
+    assert "--udid" in stderr
+
+
+def test_no_device_returns_none(monkeypatch):
+    monkeypatch.setattr(subprocess, "run", _fake_simctl("-- iOS 26.2 --\n"))
+    assert get_booted_device_udid() is None
+
+
+if __name__ == "__main__":
+    raise SystemExit(pytest.main([__file__, "-v"]))