device-devtools-mcp 0.1.0

package/scripts/ios/doctor.sh

@@ -0,0 +1,386 @@
+#!/usr/bin/env bash
+# doctor.sh — verify (and cheaply repair) everything the other scripts assume.
+#
+# Run this before the first action of a session, and again whenever any script
+# exits 3. Output is one fixed line per check, always the same checks in the same
+# order, so it can be parsed positionally:
+#
+#   <STATUS> <name> — <detail>
+#
+# STATUS is OK, WARN or FAIL. Only FAIL affects the exit code.
+#   exit 0  every required check passed
+#   exit 2  at least one required check failed
+#
+# Repairs: iproxy is started when missing, always, because it is cheap, local
+# and idempotent. WebDriverAgent is started only with --start-wda, because that
+# is a long-running xcodebuild against the device and starting it implicitly
+# would hide the reason it stopped.
+#
+#   --start-wda   start the WebDriverAgent runner if it is not answering
+#   --recover     the same, spelled the way every other script spells it when
+#                 it tells you to run this
+#
+# The runner does die on its own — twice during a single day of development —
+# so a caller with no human attached needs a way to get back on its feet. This
+# is that way, and it is opt-in rather than automatic.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+START_WDA=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --start-wda) START_WDA=1; shift ;;
+    # --recover is the platform-neutral spelling, so that any caller can ask any
+    # adapter to put itself right without knowing what "right" involves here.
+    --recover) START_WDA=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: doctor.sh [--start-wda|--recover])" 1 ;;
+  esac
+done
+
+FAILED=0
+
+# How long a freshly started WebDriverAgent runner is given to answer. See the
+# loop that uses it for why it is no longer ninety seconds.
+WDA_START_SECONDS=240
+
+# The status word is the whole point of these nine lines, so it is the only
+# thing tinted. The check names stay plain: they are a fixed list in a fixed
+# order and colouring them would suggest one matters more than another.
+say() {
+  local col=""
+  case "$1" in OK) col="$C_PASS" ;; WARN) col="$C_NOTE" ;; FAIL) col="$C_FAIL" ;; esac
+  printf '%s%s%s %s — %s\n' "$col" "$1" "${col:+$C_OFF}" "$2" "$3"
+  [ "$1" = FAIL ] && FAILED=1
+  return 0
+}
+
+# Why the runner started and never answered, read out of xcodebuild's own log.
+# One line, cause first and remedy second, because the caller may be a fleet
+# worker with nobody watching and this line is all it will report.
+#
+# The order is most-specific first: a signing failure also prints a launch
+# failure underneath it, and naming the outer symptom would send someone to the
+# wrong place.
+wda_start_failure() {
+  local log; log="$(state_dir)/wda.log"
+  [ -f "$log" ] || { echo "started the runner but it never answered"; return; }
+
+  if grep -q "Timed out while enabling automation mode" "$log"; then
+    echo "the device refused automation mode — turn on Settings > Developer > Enable UI Automation on this device, and leave the screen unlocked"
+  elif grep -qE "ApplicationVerificationFailed|valid provisioning profile|Failed to codesign|code signature" "$log"; then
+    echo "the runner is not signed for this device — register $UDID in team $(cfg '.wda.team_id' '?') and rebuild WebDriverAgent"
+  elif grep -q "Missing test product" "$log"; then
+    echo "the .xctestrun points at a test bundle that is not beside it — rebuild WebDriverAgent"
+  elif grep -qE "device is locked|passcode|Unlock the device" "$log"; then
+    echo "the device is locked — unlock it and leave it awake"
+  elif grep -qE "Unable to (install|launch)|Failed to install" "$log"; then
+    echo "the runner could not be installed on the device"
+  else
+    # Unknown, so quote what xcodebuild actually said rather than inventing a
+    # cause. Truncated because this has to stay one line.
+    local raw
+    raw="$(grep -m1 -E "^Testing failed:|encountered an error" "$log" 2>/dev/null \
+           | tr -s ' \t' ' ' | sed 's/^ *//' | head -c 160)"
+    echo "started the runner but it never answered${raw:+ — $raw}"
+  fi
+}
+
+# --- 1. xcode -----------------------------------------------------------------
+if ! command -v xcodebuild >/dev/null 2>&1; then
+  say FAIL xcode "xcodebuild not found — install Xcode and run xcode-select --switch"
+else
+  say OK xcode "$(xcodebuild -version 2>/dev/null | tr '\n' ' ' | sed 's/ *$//') at $(xcode-select -p)"
+fi
+
+# --- 2. jq --------------------------------------------------------------------
+if command -v jq >/dev/null 2>&1; then
+  say OK jq "$(jq --version)"
+else
+  say FAIL jq "not found — brew install jq"
+  exit 2   # every later check needs jq to read the config
+fi
+
+load_config
+UDID="$(cfg '.device.udid')"
+WANT_IOS="$(cfg '.device.ios_version' '')"
+
+KIND="$(ios_kind)"
+
+# --- 3. device ----------------------------------------------------------------
+#
+# The check names and their order never change between a simulator and a real
+# device, because AGENTS.md promises callers a fixed nine lines. What changes is
+# what each one means, and the detail says which.
+DEVICE_OK=0
+if [ "$KIND" = simulator ]; then
+  if ! xcrun simctl list devices -j 2>/dev/null | jq -e --arg u "$UDID" \
+        '[.devices[][] | select(.udid == $u)] | length > 0' >/dev/null 2>&1; then
+    say FAIL device "simulator $UDID not found — xcrun simctl list devices"
+  elif ! sim_booted; then
+    say FAIL device "simulator $UDID is not booted — xcrun simctl boot $UDID"
+  else
+    simname="$(xcrun simctl list devices -j 2>/dev/null | jq -r --arg u "$UDID" \
+      '[.devices | to_entries[] | .key as $rt | .value[] | select(.udid == $u) | "\(.name) (\($rt | sub(".*SimRuntime.";"") | gsub("-";" ")))"][0] // "?"')"
+    DEVICE_OK=1
+    say OK device "simulator $simname ($UDID)"
+  fi
+elif ! command -v idevice_id >/dev/null 2>&1; then
+  say FAIL device "idevice_id not found — brew install libimobiledevice"
+elif ! idevice_id -l 2>/dev/null | grep -qx "$UDID"; then
+  attached="$(idevice_id -l 2>/dev/null | tr '\n' ' ' | sed 's/ *$//')"
+  say FAIL device "$UDID not attached — attached: ${attached:-none}"
+else
+  got_ios="$(ideviceinfo -u "$UDID" -k ProductVersion 2>/dev/null || echo '?')"
+  got_name="$(ideviceinfo -u "$UDID" -k DeviceName 2>/dev/null || echo '?')"
+  DEVICE_OK=1
+  if [ -n "$WANT_IOS" ] && [ "$got_ios" != "$WANT_IOS" ]; then
+    say WARN device "$got_name iOS $got_ios attached, config says $WANT_IOS"
+  else
+    say OK device "$got_name iOS $got_ios ($UDID)"
+  fi
+fi
+
+# --- 4. developer disk image --------------------------------------------------
+# Required to launch an XCUITest runner. Unmounts on every device reboot, and
+# Xcode remounts it only when it drives the device itself, so this check catches
+# the single most common "WDA suddenly will not start" cause.
+if [ "$KIND" = simulator ]; then
+  say OK ddi "not applicable — a simulator needs no developer disk image"
+elif [ "$DEVICE_OK" -eq 0 ]; then
+  say FAIL ddi "skipped — device check failed"
+elif ! command -v ideviceimagemounter >/dev/null 2>&1; then
+  say FAIL ddi "ideviceimagemounter not found — brew install libimobiledevice"
+else
+  # COUNT THE SIGNATURES, DO NOT READ THE HIGHEST INDEX.
+  #
+  # The first version took the number out of `ImageSignature[0]:` and required
+  # it to be greater than zero. On an iOS 15 device several images are listed,
+  # so an index of 1 or more happens to appear and the check passed by luck. An
+  # iOS 27 device mounts exactly one, at index 0, and the check read the single
+  # mounted image as none — reporting a perfectly healthy phone as broken.
+  n="$(ideviceimagemounter -u "$UDID" list 2>/dev/null | grep -c '^ImageSignature\[')"
+  if [ "${n:-0}" -gt 0 ] 2>/dev/null; then
+    say OK ddi "developer disk image mounted ($n signature(s))"
+  else
+    say FAIL ddi "no developer disk image mounted — see README.md 'Developer disk image'"
+  fi
+fi
+
+# --- 5. iproxy ----------------------------------------------------------------
+LPORT="$(cfg '.wda.local_port' '8100')"
+DPORT="$(cfg '.wda.device_port' '8100')"
+IPROXY_OK=0
+if [ "$KIND" = simulator ]; then
+  # A simulator shares the host's network stack, so WebDriverAgent is already on
+  # localhost and there is nothing to forward.
+  say OK iproxy "not needed — a simulator listens on the host directly"
+  IPROXY_OK=1
+elif port_open "$LPORT"; then
+  say OK iproxy "already forwarding ${LPORT}->${DPORT}"
+  IPROXY_OK=1
+elif [ "$DEVICE_OK" -eq 0 ]; then
+  say FAIL iproxy "skipped — device check failed"
+elif ! command -v iproxy >/dev/null 2>&1; then
+  say FAIL iproxy "iproxy not found — brew install libimobiledevice"
+else
+  sd="$(state_dir)"
+  nohup iproxy -u "$UDID" "$LPORT:$DPORT" >"$sd/iproxy.log" 2>&1 &
+  echo $! >"$sd/iproxy.pid"
+  for _ in $(seq 1 25); do
+    port_open "$LPORT" && break
+    sleep 0.2
+  done
+  if port_open "$LPORT"; then
+    say OK iproxy "started ${LPORT}->${DPORT} (pid $(cat "$sd/iproxy.pid"))"
+    IPROXY_OK=1
+  else
+    say FAIL iproxy "failed to bind $LPORT — see $sd/iproxy.log"
+  fi
+fi
+
+# --- 6. WebDriverAgent HTTP ---------------------------------------------------
+WDA_OK=0
+if [ "$IPROXY_OK" -eq 0 ]; then
+  say FAIL wda "skipped — no port forward"
+else
+  status="$(curl -sS -m "$(http_timeout)" "$(wda_base)/status" 2>/dev/null || true)"
+
+  if { [ -z "$status" ] || ! printf '%s' "$status" | jq -e '.value' >/dev/null 2>&1; } \
+     && [ "$START_WDA" -eq 1 ]; then
+    xctestrun="$(ls "$(wda_derived)"/Build/Products/*.xctestrun 2>/dev/null | head -1 || true)"
+    if [ -z "$xctestrun" ]; then
+      say FAIL wda "no .xctestrun in $(wda_derived) — WebDriverAgent has not been built for this target; run: scripts/setup.sh"
+    else
+      sd="$(state_dir)"
+
+      # ON A SIMULATOR THE PORT IS WDA'S OWN, NOT A TUNNEL'S.
+      #
+      # A physical device is reached through iproxy: WebDriverAgent always
+      # listens on 8100 on the device, and the host side picks whatever local
+      # port it likes. Nothing has to be told anything.
+      #
+      # A simulator listens on the host directly, so the port in the config is
+      # the port WDA itself must bind — and the only way to tell it is USE_PORT
+      # in the runner's environment, which for xcodebuild means the .xctestrun
+      # rather than this shell. Without this, every simulator would bind 8100
+      # and the second one would lose, silently, to a fleet that then drove the
+      # first simulator twice.
+      #
+      # MJPEG_SERVER_PORT gets the same treatment for the same reason; WDA
+      # defaults it to 9100 and two of them would collide.
+      #
+      # The modified copy is written BESIDE THE ORIGINAL, not into the state
+      # directory. Every path inside an .xctestrun is relative to __TESTROOT__,
+      # which xcodebuild resolves to the directory the file is sitting in — move
+      # the file and it looks for the test bundle next to the copy, does not
+      # find it, and fails with "Missing test product" naming a directory that
+      # was never going to contain one. Measured, once.
+      if [ "$KIND" = simulator ]; then
+        port_xctestrun="$(dirname "$xctestrun")/devicetools-$LPORT.xctestrun"
+        if cp "$xctestrun" "$port_xctestrun" 2>/dev/null \
+           && plutil -replace WebDriverAgentRunner.EnvironmentVariables.USE_PORT \
+                -string "$LPORT" "$port_xctestrun" 2>/dev/null \
+           && plutil -replace WebDriverAgentRunner.EnvironmentVariables.MJPEG_SERVER_PORT \
+                -string "$(( LPORT + 1000 ))" "$port_xctestrun" 2>/dev/null; then
+          xctestrun="$port_xctestrun"
+        else
+          rm -f "$port_xctestrun"
+        fi
+      fi
+
+      # A RUNNER THAT STOPPED ANSWERING IS STILL A RUNNER.
+      #
+      # Reaching here means /status did not answer, and --recover is the retry
+      # path a caller takes when it loses the connection. It used to start a
+      # second xcodebuild and overwrite wda.pid, orphaning the first: two
+      # runners driving one simulator, both bound to the same port, answering
+      # curl 52 (empty reply) about half the time. Measured — three of them
+      # accumulated in one session, and the run they broke looked like an
+      # application fault, which is the worst way for this to present.
+      #
+      # A flaky connection is exactly the condition that calls this repeatedly,
+      # so an unbounded supply of runners is what the old code promised.
+      if [ -f "$sd/wda.pid" ]; then
+        old="$(cat "$sd/wda.pid" 2>/dev/null || true)"
+        if [ -n "$old" ] && kill -0 "$old" 2>/dev/null; then
+          kill "$old" 2>/dev/null || true
+          for _ in 1 2 3 4 5; do kill -0 "$old" 2>/dev/null || break; sleep 1; done
+          kill -9 "$old" 2>/dev/null || true
+        fi
+      fi
+
+      nohup xcodebuild test-without-building -xctestrun "$xctestrun" \
+        -destination "id=$UDID" >"$sd/wda.log" 2>&1 &
+      echo $! >"$sd/wda.pid"
+      # A COLD MACHINE IS NOT A WARM ONE, AND CI IS ALWAYS COLD.
+      #
+      # Ninety seconds was measured on a laptop whose simulator had been booted
+      # for hours. On a GitHub runner the simulator was minted a minute earlier
+      # and the runner app is being launched for the first time: one CI run
+      # answered inside the budget and the next one did not, on identical code.
+      # Nothing waits this long normally — it polls, so a warm start still
+      # returns in a second or two, and the number only decides how patient the
+      # failure is. The Android adapter learned the same lesson on the same day.
+      for _ in $(seq 1 "$WDA_START_SECONDS"); do
+        curl -sS -m 3 "$(wda_base)/status" >/dev/null 2>&1 && break
+        sleep 1
+      done
+      status="$(curl -sS -m "$(http_timeout)" "$(wda_base)/status" 2>/dev/null || true)"
+    fi
+  fi
+
+  if [ -z "$status" ] || ! printf '%s' "$status" | jq -e '.value' >/dev/null 2>&1; then
+    if [ "$START_WDA" -eq 1 ]; then
+      # THE LOG KNOWS WHY. SAY IT.
+      #
+      # "see the log" is the answer a tool gives when it has not looked. Every
+      # cause below is a fixed string xcodebuild prints, and each one has a
+      # different remedy — a per-device setting, a signing problem, and a
+      # locked screen are not the same failure and must not read as one.
+      #
+      # Found by putting a second iPhone on the fleet: the runner installed,
+      # launched, and timed out enabling automation mode, and the only thing
+      # this line said was to go and read a 400-line xcodebuild log.
+      say FAIL wda "$(wda_start_failure) after ${WDA_START_SECONDS}s — see $(state_dir)/wda.log"
+    else
+      say FAIL wda "no answer on $(wda_base)/status — retry with: $(as_cmd doctor --recover)"
+    fi
+  else
+    ios="$(printf '%s' "$status" | jq -r '.value.os.version // "?"')"
+    ver="$(printf '%s' "$status" | jq -r '.value.build.version // .value.build.time // "?"')"
+    say OK wda "ready, WDA $ver driving iOS $ios"
+    WDA_OK=1
+  fi
+fi
+
+# --- 7. WebDriverAgent session ------------------------------------------------
+# A live HTTP port is not proof that XCUITest can still drive the UI: the runner
+# outlives its test bundle in some failure modes. Creating a real session is.
+if [ "$WDA_OK" -eq 0 ]; then
+  say FAIL wda-session "skipped — WDA not answering"
+else
+  resp="$(curl -sS -m "$(http_timeout)" -X POST -H 'Content-Type: application/json' \
+    -d '{"capabilities":{"alwaysMatch":{}}}' "$(wda_base)/session" 2>/dev/null || true)"
+  sid="$(printf '%s' "$resp" | jq -r '.value.sessionId // .sessionId // empty' 2>/dev/null || true)"
+  if [ -z "$sid" ]; then
+    msg="$(printf '%s' "$resp" | jq -r '.value.error // .value.message // "unknown error"' 2>/dev/null | head -c 120)"
+    say FAIL wda-session "could not create a session — $msg"
+  else
+    # The session capabilities WDA returns carry no bundle id, so ask what is
+    # actually on screen. That also proves the runner can introspect a foreign
+    # app, which is the capability every other script depends on.
+    fg="$(curl -sS -m "$(http_timeout)" "$(wda_base)/wda/activeAppInfo" 2>/dev/null \
+          | jq -r '.value.bundleId // empty' 2>/dev/null || true)"
+    curl -sS -m "$(http_timeout)" -X DELETE "$(wda_base)/session/$sid" >/dev/null 2>&1 || true
+    say OK wda-session "created and released, foreground app ${fg:-unknown}"
+  fi
+fi
+
+# --- 8. app under test --------------------------------------------------------
+APP_ID="$(cfg '.app.bundle_id' '')"
+if [ -z "$APP_ID" ]; then
+  say WARN app "app.bundle_id not set in $DT_CONFIG — install and launch checks unavailable"
+elif [ "$DEVICE_OK" -eq 0 ]; then
+  say FAIL app "skipped — device check failed"
+elif [ "$KIND" = simulator ]; then
+  if xcrun simctl get_app_container "$UDID" "$APP_ID" app >/dev/null 2>&1; then
+    say OK app "$APP_ID installed"
+  else
+    say FAIL app "$APP_ID not installed on the simulator — $(as_cmd app install '<path>')"
+  fi
+elif ! command -v ios-deploy >/dev/null 2>&1; then
+  say FAIL app "ios-deploy not found — brew install ios-deploy"
+elif ios-deploy --id "$UDID" --no-wifi --exists --bundle_id "$APP_ID" >/dev/null 2>&1; then
+  # The device does not volunteer a version, so what is reported is what
+  # DeviceTools put there — a smaller claim, and a true one. Anything installed
+  # by other means says so rather than being described from a stale record.
+  rec="$(last_install)"
+  rec_id="$(printf '%s' "$rec" | cut -f1)"
+  if [ -n "$rec" ] && [ "$rec_id" = "$APP_ID" ]; then
+    say OK app "$APP_ID installed — $(printf '%s' "$rec" | cut -f2) ($(printf '%s' "$rec" | cut -f3)), put there by DeviceTools at $(printf '%s' "$rec" | cut -f5)"
+  else
+    say OK app "$APP_ID installed — version unknown, not installed by DeviceTools"
+  fi
+else
+  say FAIL app "$APP_ID not installed — $(as_cmd app install)"
+fi
+
+# THERE IS NO SECTION 9, AND THERE WILL NOT BE ONE.
+#
+# It read the signing identities and provisioning profiles on this machine and
+# tried to say whether a build would install. Deleted at the second complaint,
+# and the complaint was right: this tool owns the phone from "the app is
+# installed" onward. Whose certificate signs the app, which team owns it and
+# which profile Xcode picked are the build's business, and a check standing
+# outside the build can only guess at them — it guessed wrong twice, naming a
+# team the project has nothing to do with, on a machine with fifteen of them.
+#
+# `app install` still refuses an unsigned bundle. That is a different question:
+# it is about whether the verb in front of you will work, not about auditing
+# somebody's account. It also comes from the bundle itself rather than from
+# what happens to be lying in the keychain.
+#
+# profiles_for and project_signing went with it.
+
+exit $(( FAILED ? 2 : 0 ))