mobile-debug-mcp 0.21.5 → 0.23.0

package/src/interact/index.ts

@@ -1,9 +1,11 @@
+import { createHash } from 'crypto'
 import { AndroidInteract } from './android.js';
 import { iOSInteract } from './ios.js';
 export { AndroidInteract, iOSInteract };
 
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { ToolsObserve } from '../observe/index.js'
+import type { TapElementResponse } from '../types.js'
 
 interface ScreenFingerprintResponse { fingerprint: string | null }
 
@@ -29,14 +31,159 @@ interface UiElement {
   _interactable?: boolean
 }
 
+interface ResolvedUiElementContext {
+  elementId: string
+  platform: 'android' | 'ios'
+  deviceId?: string
+  bounds: [number, number, number, number] | null
+  index: number
+}
+
 
 export class ToolsInteract {
+  private static readonly _maxResolvedUiElements = 256
+  private static _resolvedUiElements = new Map<string, ResolvedUiElementContext>()
 
   private static _normalize(s: any): string {
     if (s === null || s === undefined) return ''
     try { return String(s).toLowerCase().trim() } catch { return '' }
   }
 
+  private static _normalizeBounds(bounds: any): [number, number, number, number] | null {
+    if (!Array.isArray(bounds) || bounds.length < 4) return null
+    const normalized = bounds.slice(0, 4).map((value: any) => Number(value))
+    if (normalized.some((value: number) => Number.isNaN(value))) return null
+    return normalized as [number, number, number, number]
+  }
+
+  private static _isVisibleElement(el: UiElement): boolean {
+    const bounds = ToolsInteract._normalizeBounds(el.bounds)
+    return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1]
+  }
+
+  private static _computeElementId(platform: 'android' | 'ios', deviceId: string | undefined, el: UiElement, index: number): string {
+    const identity = {
+      platform,
+      deviceId: deviceId || '',
+      text: ToolsInteract._normalize(el.text ?? el.label ?? el.value ?? ''),
+      resourceId: ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+      accessibilityId: ToolsInteract._normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? ''),
+      class: ToolsInteract._normalize(el.type ?? el.class ?? ''),
+      bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+      index
+    }
+    return `el_${createHash('sha1').update(JSON.stringify(identity)).digest('hex').slice(0, 24)}`
+  }
+
+  private static _buildResolvedElement(platform: 'android' | 'ios', deviceId: string | undefined, el: UiElement, index: number) {
+    const bounds = ToolsInteract._normalizeBounds(el.bounds)
+    const elementId = ToolsInteract._computeElementId(platform, deviceId, el, index)
+
+    ToolsInteract._rememberResolvedElement(elementId, {
+      elementId,
+      platform,
+      deviceId,
+      bounds,
+      index
+    })
+
+    return {
+      text: el.text ?? null,
+      resource_id: el.resourceId ?? el.resourceID ?? el.id ?? null,
+      accessibility_id: el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? null,
+      class: el.type ?? el.class ?? null,
+      bounds,
+      index,
+      elementId
+    }
+  }
+
+  private static _rememberResolvedElement(elementId: string, context: ResolvedUiElementContext) {
+    if (ToolsInteract._resolvedUiElements.has(elementId)) {
+      ToolsInteract._resolvedUiElements.delete(elementId)
+    }
+
+    ToolsInteract._resolvedUiElements.set(elementId, context)
+
+    while (ToolsInteract._resolvedUiElements.size > ToolsInteract._maxResolvedUiElements) {
+      const oldestElementId = ToolsInteract._resolvedUiElements.keys().next().value
+      if (!oldestElementId) break
+      ToolsInteract._resolvedUiElements.delete(oldestElementId)
+    }
+  }
+
+  static _resetResolvedUiElementsForTests() {
+    ToolsInteract._resolvedUiElements.clear()
+  }
+
+  private static _findCurrentResolvedElement(
+    elements: UiElement[],
+    platform: 'android' | 'ios',
+    deviceId: string | undefined,
+    resolved: ResolvedUiElementContext
+  ): { el: UiElement, index: number } | null {
+    const indexedCandidate = elements[resolved.index]
+    if (indexedCandidate && ToolsInteract._computeElementId(platform, deviceId, indexedCandidate, resolved.index) === resolved.elementId) {
+      return { el: indexedCandidate, index: resolved.index }
+    }
+
+    return null
+  }
+
+  private static _resolveActionableAncestor(elements: UiElement[], chosen: { el: UiElement, idx: number } | null): { el: UiElement, idx: number } | null {
+    if (!chosen) return null
+    if (chosen.el.clickable || chosen.el.focusable) return chosen
+
+    let current = chosen
+    let safety = 0
+
+    while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable) && current.el.parentId !== undefined && current.el.parentId !== null) {
+      const parentId = current.el.parentId
+      let parentIndex: number | null = null
+
+      if (typeof parentId === 'number') parentIndex = parentId
+      else if (typeof parentId === 'string' && /^\d+$/.test(parentId)) parentIndex = Number(parentId)
+
+      if (parentIndex !== null && elements[parentIndex]) {
+        current = { el: elements[parentIndex], idx: parentIndex }
+        if (current.el.clickable || current.el.focusable) return current
+      } else if (typeof parentId === 'string') {
+        const foundIndex = elements.findIndex((el) => el.resourceId === parentId || el.id === parentId)
+        if (foundIndex === -1) break
+        current = { el: elements[foundIndex], idx: foundIndex }
+        if (current.el.clickable || current.el.focusable) return current
+      } else {
+        break
+      }
+
+      safety++
+    }
+
+    const childBounds = ToolsInteract._normalizeBounds(chosen.el.bounds)
+    if (!childBounds) return null
+    const [cl, ct, cr, cb] = childBounds
+
+    let best: { el: UiElement, idx: number } | null = null
+    let bestArea = Infinity
+
+    for (let i = 0; i < elements.length; i++) {
+      const el = elements[i]
+      if (!el || !(el.clickable || el.focusable)) continue
+      const bounds = ToolsInteract._normalizeBounds(el.bounds)
+      if (!bounds) continue
+      const [pl, pt, pr, pb] = bounds
+      if (pl <= cl && pt <= ct && pr >= cr && pb >= cb) {
+        const area = (pr - pl) * (pb - pt)
+        if (area < bestArea) {
+          bestArea = area
+          best = { el, idx: i }
+        }
+      }
+    }
+
+    return best
+  }
+
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
     const effectivePlatform = platform || 'android'
@@ -50,6 +197,99 @@ export class ToolsInteract {
     return await interact.tap(x, y, resolved.id)
   }
 
+  static async tapElementHandler({ elementId }: { elementId: string }): Promise<TapElementResponse> {
+    const action = 'tap' as const
+    const resolved = ToolsInteract._resolvedUiElements.get(elementId)
+    if (!resolved) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'element_not_found',
+          message: 'Element ID was not found in the current UI context'
+        }
+      }
+    }
+
+    const tree = await ToolsObserve.getUITreeHandler({ platform: resolved.platform, deviceId: resolved.deviceId }) as any
+    const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : resolved.platform
+    const treeDeviceId = tree?.device?.id || resolved.deviceId
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const currentMatch = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved)
+
+    if (!currentMatch) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'element_not_found',
+          message: 'Element ID is not present in the current UI context'
+        }
+      }
+    }
+
+    if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'element_not_visible',
+          message: 'Element is not visible'
+        }
+      }
+    }
+
+    if (currentMatch.el.enabled === false) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'element_not_enabled',
+          message: 'Element is not enabled'
+        }
+      }
+    }
+
+    const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds
+    if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'element_not_visible',
+          message: 'Element does not have valid visible bounds'
+        }
+      }
+    }
+
+    const x = Math.floor((bounds[0] + bounds[2]) / 2)
+    const y = Math.floor((bounds[1] + bounds[3]) / 2)
+    const tapResult = await ToolsInteract.tapHandler({ platform: resolved.platform, x, y, deviceId: resolved.deviceId })
+
+    if (!tapResult.success) {
+      return {
+        success: false,
+        elementId,
+        action,
+        error: {
+          code: 'tap_failed',
+          message: tapResult.error || 'Tap failed'
+        }
+      }
+    }
+
+    return {
+      success: true,
+      elementId,
+      action
+    }
+  }
+
   static async swipeHandler({ platform = 'android', x1, y1, x2, y2, duration, deviceId }: { platform?: 'android' | 'ios', x1: number, y1: number, x2: number, y2: number, duration: number, deviceId?: string }) {
     const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId)
     return await interact.swipe(x1, y1, x2, y2, duration, resolved.id)
@@ -335,6 +575,7 @@ export class ToolsInteract {
             }
 
             let conditionMet = false
+            let matchedElement = chosen
             if (condition === 'exists') {
               // when an index is specified, existence requires that specific index be present
               conditionMet = (pickIndex !== undefined) ? (chosen !== null) : (matchedCount >= 1)
@@ -348,11 +589,12 @@ export class ToolsInteract {
                 conditionMet = visibleFlag
               } else conditionMet = false
             } else if (condition === 'clickable') {
-              if (chosen) {
-                const b = chosen.el.bounds
-                const visibleFlag = !!chosen.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
-                const enabled = !!chosen.el.enabled
-                const clickable = !!chosen.el.clickable || !!chosen.el._interactable
+              matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen as { el: UiElement, idx: number }) || chosen) : null
+              if (matchedElement) {
+                const b = matchedElement.el.bounds
+                const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
+                const enabled = !!matchedElement.el.enabled
+                const clickable = !!matchedElement.el.clickable || !!matchedElement.el._interactable || !!matchedElement.el.focusable
                 conditionMet = visibleFlag && enabled && clickable
               } else conditionMet = false
             }
@@ -361,14 +603,9 @@ export class ToolsInteract {
               const now = Date.now()
               const latency_ms = now - overallStart
               // Build element output per spec
-              const outEl = chosen ? {
-                text: chosen.el.text ?? null,
-                resource_id: chosen.el.resourceId ?? chosen.el.resourceID ?? chosen.el.id ?? null,
-                accessibility_id: chosen.el.contentDescription ?? chosen.el.contentDesc ?? chosen.el.accessibilityLabel ?? chosen.el.label ?? null,
-                class: chosen.el.type ?? chosen.el.class ?? null,
-                bounds: Array.isArray(chosen.el.bounds) && chosen.el.bounds.length >= 4 ? chosen.el.bounds : null,
-                index: chosen.idx
-              } : null
+              const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
+              const resolvedDeviceId = tree?.device?.id || deviceId
+              const outEl = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null
 
               return {
                 status: 'success',

package/src/network/index.ts

@@ -0,0 +1,268 @@
+import { execAdb, parseLogLine } from '../utils/android/utils.js'
+import { execCommand } from '../utils/ios/utils.js'
+
+export type NetworkErrorCode =
+  | 'timeout'
+  | 'dns_error'
+  | 'tls_error'
+  | 'connection_refused'
+  | 'connection_reset'
+  | 'unknown_network_error'
+
+export type NetworkActivityStatus = 'success' | 'failure' | 'retryable'
+
+export interface NetworkEvent {
+  endpoint: string
+  method: string
+  statusCode: number | null
+  networkError: NetworkErrorCode | null
+  status: NetworkActivityStatus
+  durationMs: number
+}
+
+export interface GetNetworkActivityResult {
+  requests: NetworkEvent[]
+  count: number
+}
+
+// ─── Module state ─────────────────────────────────────────────────────────────
+// lastActionTimestamp: set when an action tool fires (tap, swipe, etc.)
+// lastConsumedTimestamp: advanced after each get_network_activity call to prevent duplicates
+let lastActionTimestamp = 0
+let lastConsumedTimestamp = 0
+
+export function notifyActionStart(): void {
+  lastActionTimestamp = Date.now()
+  lastConsumedTimestamp = 0
+}
+
+/** Exposed for unit tests only. */
+export function _setTimestampsForTests(actionTs: number, consumedTs: number): void {
+  lastActionTimestamp = actionTs
+  lastConsumedTimestamp = consumedTs
+}
+
+// ─── Parsing constants ────────────────────────────────────────────────────────
+const URL_RE = /https?:\/\/[^\s"'\]\)><]+/
+const PATH_RE = /\/[a-zA-Z0-9_.-]+(?:\/[a-zA-Z0-9_.-]+)+/
+const METHOD_RE = /\b(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b/
+
+const NETWORK_ERROR_PATTERNS: Array<{ re: RegExp; code: NetworkErrorCode }> = [
+  { re: /timed?\s*out|timeout/i, code: 'timeout' },
+  { re: /dns|name[\s_]resolution|host\s*not\s*found|nodename/i, code: 'dns_error' },
+  { re: /\btls\b|\bssl\b|certificate|handshake/i, code: 'tls_error' },
+  { re: /connection\s*refused/i, code: 'connection_refused' },
+  { re: /connection\s*reset|reset\s*by\s*peer/i, code: 'connection_reset' },
+]
+
+const BACKGROUND_TOKENS = ['/analytics', '/metrics', '/tracking', '/log', '/events', '/telemetry', '/ping', '/beacon']
+const BACKGROUND_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.css', '.js', '.svg', '.ico', '.woff', '.ttf']
+const FILESYSTEM_PREFIXES = ['/data/', '/system/', '/apex/', '/proc/', '/dev/', '/vendor/', '/product/', '/storage/', '/sdcard/', '/mnt/', '/odm/', '/cache/', '/metadata/', '/acct/', '/sys/']
+const FILESYSTEM_EXTENSIONS = ['.apk', '.apex', '.odex', '.vdex', '.dex', '.so', '.jar', '.bin', '.img', '.db', '.sqlite', '.c', '.cc', '.cpp', '.cxx', '.h', '.hpp', '.m', '.mm', '.kt', '.java', '.swift']
+
+// ─── Parsing helpers ─────────────────────────────────────────────────────────
+
+function extractUrl(text: string): string | null {
+  const m = text.match(URL_RE)
+  return m ? m[0] : null
+}
+
+function isPlausibleEndpointPath(path: string): boolean {
+  const lower = path.toLowerCase()
+  if (!lower.startsWith('/')) return false
+  if (FILESYSTEM_PREFIXES.some((prefix) => lower.startsWith(prefix))) return false
+  if (FILESYSTEM_EXTENSIONS.some((ext) => lower.endsWith(ext))) return false
+  return true
+}
+
+function extractPath(text: string): string | null {
+  const m = text.match(PATH_RE)
+  if (!m) return null
+  return isPlausibleEndpointPath(m[0]) ? m[0] : null
+}
+
+function toStatusCode(value: string | undefined): number | null {
+  if (!value) return null
+  const code = Number(value)
+  return code >= 100 && code <= 599 ? code : null
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+function extractStatusCode(text: string, url: string | null, path: string | null, method: string | null): number | null {
+  const directHttpMatch = text.match(/\bHTTP\/\d(?:\.\d)?\s+([1-5]\d{2})\b/i) || text.match(/\bHTTP\s+([1-5]\d{2})\b/i)
+  if (directHttpMatch) return toStatusCode(directHttpMatch[1])
+
+  const endpointToken = url || path
+  const hasEndpointContext = endpointToken !== null
+  if (!hasEndpointContext && method === null) return null
+
+  const labeledMatch = text.match(/\b(?:status(?:\s*code)?|response(?:\s*code)?)\s*[:=]?\s*([1-5]\d{2})\b/i)
+  if (labeledMatch && hasEndpointContext) return toStatusCode(labeledMatch[1])
+
+  if (endpointToken) {
+    const escapedEndpoint = escapeRegExp(endpointToken)
+    const endpointThenCode = new RegExp(`${escapedEndpoint}[^\\n]*?\\b([1-5]\\d{2})\\b`, 'i')
+    const codeThenEndpoint = new RegExp(`\\b([1-5]\\d{2})\\b[^\\n]*?${escapedEndpoint}`, 'i')
+    const contextualMatch = text.match(endpointThenCode) || text.match(codeThenEndpoint)
+    if (contextualMatch) return toStatusCode(contextualMatch[1])
+  }
+
+  if (method !== null && path !== null) {
+    const methodPathCodeMatch = text.match(/\b(?:GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)\b[^\n]*?\b([1-5]\d{2})\b/i)
+    if (methodPathCodeMatch) return toStatusCode(methodPathCodeMatch[1])
+  }
+
+  return null
+}
+
+function extractMethod(text: string): string | null {
+  const m = text.match(METHOD_RE)
+  return m ? m[1] : null
+}
+
+function detectNetworkError(text: string): NetworkErrorCode | null {
+  for (const { re, code } of NETWORK_ERROR_PATTERNS) {
+    if (re.test(text)) return code
+  }
+  return null
+}
+
+export function normalizeEndpoint(raw: string): string {
+  try {
+    const u = new URL(raw.startsWith('/') ? `https://x${raw}` : raw)
+    const p = u.pathname.toLowerCase().replace(/\/+$/, '')
+    return p || '/'
+  } catch {
+    return raw.toLowerCase().replace(/\?.*$/, '').replace(/\/+$/, '') || '/'
+  }
+}
+
+export function classifyStatus(statusCode: number | null, networkError: NetworkErrorCode | null): NetworkActivityStatus {
+  if (networkError !== null) return 'retryable'
+  if (statusCode === null) return 'success' // request detected, no failure signal
+  if (statusCode >= 200 && statusCode <= 299) return 'success'
+  if (statusCode >= 400 && statusCode <= 499) return 'failure'
+  return 'retryable' // 5xx, 1xx, 3xx
+}
+
+function meetsEmissionCriteria(url: string | null, path: string | null, statusCode: number | null, method: string | null): boolean {
+  if (url !== null) return true                      // condition 1: full http/https URL
+  if (statusCode !== null) return true               // condition 2: valid HTTP status code
+  if (method !== null && path !== null) return true  // condition 3: method + path
+  return false
+}
+
+function classifyEventType(endpoint: string): 'primary' | 'background' {
+  const lower = endpoint.toLowerCase()
+  if (BACKGROUND_TOKENS.some(t => lower.includes(t))) return 'background'
+  if (BACKGROUND_EXTENSIONS.some(e => lower.endsWith(e))) return 'background'
+  return 'primary'
+}
+
+function filterToSignificantEvents(events: NetworkEvent[]): NetworkEvent[] {
+  if (events.length === 0) return events
+  const hasPrimary = events.some(e => classifyEventType(e.endpoint) === 'primary')
+  return hasPrimary ? events.filter(e => classifyEventType(e.endpoint) === 'primary') : events
+}
+
+/** Exported for unit testing. */
+export function parseMessageToEvent(message: string): NetworkEvent | null {
+  const url = extractUrl(message)
+  const path = url ? null : extractPath(message)
+  const method = extractMethod(message)
+  const statusCode = extractStatusCode(message, url, path, method)
+  const networkError = detectNetworkError(message)
+
+  if (!meetsEmissionCriteria(url, path, statusCode, method)) return null
+
+  const rawEndpoint = url || path || 'unknown'
+  return {
+    endpoint: normalizeEndpoint(rawEndpoint),
+    method: method || 'unknown',
+    statusCode,
+    networkError,
+    status: classifyStatus(statusCode, networkError),
+    durationMs: 0
+  }
+}
+
+// ─── Android ─────────────────────────────────────────────────────────────────
+
+async function getAndroidEvents(sinceMs: number, deviceId?: string): Promise<NetworkEvent[]> {
+  try {
+    const stdout = await execAdb(['logcat', '-d', '-v', 'threadtime', '*:V', '-t', '2000'], deviceId)
+    const lines = stdout ? stdout.split(/\r?\n/).filter(Boolean) : []
+
+    const events: NetworkEvent[] = []
+    for (const line of lines) {
+      const parsed = parseLogLine(line)
+      if (parsed._iso) {
+        const ts = new Date(parsed._iso).getTime()
+        if (ts > 0 && ts <= sinceMs) continue
+      }
+      const event = parseMessageToEvent(parsed.message || line)
+      if (event) events.push(event)
+    }
+    return events
+  } catch {
+    return []
+  }
+}
+
+// ─── iOS ─────────────────────────────────────────────────────────────────────
+
+async function getIOSEvents(sinceMs: number, deviceId = 'booted'): Promise<NetworkEvent[]> {
+  try {
+    const lookbackSeconds = Math.max(15, Math.ceil((Date.now() - sinceMs) / 1000) + 5)
+    const args = [
+      'simctl', 'spawn', deviceId, 'log', 'show',
+      '--last', `${lookbackSeconds}s`,
+      '--style', 'syslog',
+      '--predicate', 'eventMessage contains "http" OR eventMessage contains "URLSession" OR eventMessage contains "Task <" OR eventMessage contains "HTTP/"'
+    ]
+    const result = await execCommand(args, deviceId)
+    const lines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : []
+
+    const events: NetworkEvent[] = []
+    for (const line of lines) {
+      const tsMatch = line.match(/^(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})/)
+      if (tsMatch) {
+        const ts = new Date(tsMatch[1]).getTime()
+        if (ts > 0 && ts <= sinceMs) continue
+      }
+      const event = parseMessageToEvent(line)
+      if (event) events.push(event)
+    }
+    return events
+  } catch {
+    return []
+  }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export class ToolsNetwork {
+  static notifyActionStart(): void {
+    notifyActionStart()
+  }
+
+  static async getNetworkActivity(params: { platform: string; deviceId?: string }): Promise<GetNetworkActivityResult> {
+    const { platform, deviceId } = params
+
+    const sinceMs = lastConsumedTimestamp > lastActionTimestamp
+      ? lastConsumedTimestamp
+      : lastActionTimestamp > 0 ? lastActionTimestamp : Date.now() - 30000
+
+    const raw = platform === 'android'
+      ? await getAndroidEvents(sinceMs, deviceId)
+      : await getIOSEvents(sinceMs, deviceId)
+
+    const requests = filterToSignificantEvents(raw)
+    lastConsumedTimestamp = Date.now()
+
+    return { requests, count: requests.length }
+  }
+}

package/src/observe/ios.ts

@@ -9,6 +9,15 @@ import { computeScreenFingerprint } from '../utils/ui/index.js'
 import { parsePngSize } from '../utils/image.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+let iosExecCommand = execCommand
+
+export function _setIOSExecCommandForTests(fn: typeof execCommand) {
+  iosExecCommand = fn
+}
+
+export function _resetIOSExecCommandForTests() {
+  iosExecCommand = execCommand
+}
 
 interface IDBElement {
   AXFrame?: { x: number | string, y: number | string, width: number | string, height: number | string, w?: number | string, h?: number | string };
@@ -157,7 +166,7 @@ export class iOSObserve {
         const parts = appId.split('.')
         const simpleName = parts[parts.length - 1]
         try {
-          const pgrepRes = await execCommand(['simctl','spawn', deviceId, 'pgrep', '-f', simpleName], deviceId)
+          const pgrepRes = await iosExecCommand(['simctl','spawn', deviceId, 'pgrep', '-f', simpleName], deviceId)
           const out = pgrepRes && pgrepRes.output ? pgrepRes.output.trim() : ''
           const firstLine = out.split(/\r?\n/).find(Boolean)
           if (firstLine) {
@@ -169,7 +178,7 @@ export class iOSObserve {
         }
       }
       const effectivePid = pid || detectedPid || null
-      const result = await execCommand(args, deviceId)
+      const result = await iosExecCommand(args, deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
       const rawLines = result.output ? result.output.split(/\r?\n/).filter(Boolean) : []
 
@@ -281,7 +290,7 @@ export class iOSObserve {
     const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`
 
     try {
-      await execCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId)
+      await iosExecCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId)
       
       const buffer = await fs.readFile(tmpFile)
       const base64 = buffer.toString('base64')