mobile-debug-mcp 0.15.0 → 0.17.0

package/src/utils/exec.ts

@@ -0,0 +1,33 @@
+import { spawn } from 'child_process'
+
+export type ExecOptions = { timeout?: number; env?: NodeJS.ProcessEnv; cwd?: string; shell?: boolean }
+
+export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {}): Promise<{ exitCode: number | null, stdout: string, stderr: string }> {
+  const { timeout = 0, env, cwd, shell } = opts
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell })
+    let stdout = ''
+    let stderr = ''
+    if (child.stdout) child.stdout.on('data', (d) => { stdout += d.toString() })
+    if (child.stderr) child.stderr.on('data', (d) => { stderr += d.toString() })
+
+    let timedOut = false
+    const timer = timeout && timeout > 0 ? setTimeout(() => {
+      timedOut = true
+      try { child.kill() } catch { }
+      resolve({ exitCode: null, stdout: stdout.trim(), stderr: stderr.trim() })
+    }, timeout) : null
+
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer)
+      if (timedOut) return
+      resolve({ exitCode: code, stdout: stdout.trim(), stderr: stderr.trim() })
+    })
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer)
+      reject(err)
+    })
+  })
+}
+

package/src/{interact/shared/scroll_to_element.ts → utils/ui/index.ts}

@@ -1,4 +1,76 @@
-import { UIElement, GetUITreeResponse, SwipeResponse } from '../../types.js'
+import crypto from 'crypto'
+import { GetUITreeResponse, GetCurrentScreenResponse, UIElement, SwipeResponse } from '../../types.js'
+
+const ANDROID_STRUCTURAL_TYPES = ['Window','Application','View','ViewGroup','LinearLayout','FrameLayout','RelativeLayout','ScrollView','RecyclerView','TextView','ImageView']
+const IOS_STRUCTURAL_TYPES = ['Window','Application','View','ViewController','UITableView','UICollectionView','UILabel','UIImageView','UIView','UIWindow','UIStackView','UITextView','UITableViewCell']
+
+function isDynamicText(t?: string): boolean {
+  if (!t) return false
+  const txt = t.trim()
+  if (!txt) return false
+  if (/\b\d{1,2}:\d{2}\b/.test(txt)) return true
+  if (/\b\d{4}-\d{2}-\d{2}\b/.test(txt)) return true
+  if (/^\d+(?:\.\d+)?%$/.test(txt)) return true
+  if (/^\d+$/.test(txt)) return true
+  if (/^[\d,]{1,10}$/.test(txt)) return true
+  return false
+}
+
+function normalizeElement(e: UIElement) {
+  return {
+    type: (e.type || '').toString(),
+    resourceId: (e.resourceId || '').toString(),
+    text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
+    contentDesc: (e.contentDescription || '').toString(),
+    bounds: Array.isArray(e.bounds) ? e.bounds.slice(0,4).map((n:any)=>Number(n)||0) : [0,0,0,0]
+  }
+}
+
+export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCurrentScreenResponse | null, platform: 'android' | 'ios', limit: number = 50): { fingerprint: string | null; activity?: string; error?: string } {
+  try {
+    if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
+
+    const activity = current && (current.activity || (current as any).shortActivity) ? (current.activity || (current as any).shortActivity) : ''
+
+    const candidates: UIElement[] = (tree.elements || []).filter(e => {
+      if (!e) return false
+      if (!e.visible) return false
+      const hasStableText = typeof e.text === 'string' && e.text.trim().length > 0
+      const hasResource = !!e.resourceId
+      const interactable = !!e.clickable || !!e.enabled
+      const structuralList = platform === 'android' ? ANDROID_STRUCTURAL_TYPES : IOS_STRUCTURAL_TYPES
+      const structurallySignificant = hasStableText || hasResource || structuralList.includes(e.type || '')
+      return interactable || structurallySignificant
+    }) as UIElement[]
+
+    const normalized = candidates.map(normalizeElement)
+
+    const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0))
+
+    filteredNormalized.sort((a,b) => {
+      const ay = (a.bounds && a.bounds[1]) || 0
+      const by = (b.bounds && b.bounds[1]) || 0
+      if (ay !== by) return ay - by
+      const ax = (a.bounds && a.bounds[0]) || 0
+      const bx = (b.bounds && b.bounds[0]) || 0
+      return ax - bx
+    })
+
+    const limited = filteredNormalized.slice(0, Math.max(0, limit))
+
+    const payload = {
+      activity: platform === 'android' ? (activity || '') : '',
+      resolution: (tree as any).resolution || { width: 0, height: 0 },
+      elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
+    }
+
+    const combined = JSON.stringify(payload)
+    const hash = crypto.createHash('sha256').update(combined).digest('hex')
+    return { fingerprint: hash, activity: activity }
+  } catch (e) {
+    return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
+  }
+}
 
 export interface ScrollSelector { text?: string; resourceId?: string; contentDesc?: string; className?: string }
 
@@ -84,7 +156,6 @@ export async function scrollToElementShared(opts: {
     try {
       await swipe(x1, y1, x2, y2, duration, deviceId)
     } catch (e) {
-      // Log swipe failures to aid debugging but don't fail the overall flow
       try { console.warn(`scrollToElement swipe failed: ${e instanceof Error ? e.message : String(e)}`) } catch {}
     }
 

package/test/interact/unit/wait_for_screen_change.test.ts

@@ -0,0 +1,32 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+const original = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+async function runTests() {
+  console.log('Starting tests for wait_for_screen_change...')
+
+  // Test 1: Immediate change
+  let seq1: Array<string | null> = ['B','B']
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null })
+  const start1 = Date.now()
+  const res1 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 2000, pollIntervalMs: 50 })
+  const elapsed1 = Date.now() - start1
+  console.log('Test 1: Immediate change ->', (res1 && (res1 as any).success === true && (res1 as any).newFingerprint === 'B') ? 'PASS' : 'FAIL', 'Elapsed:', elapsed1, 'ms')
+
+  // Test 2: Transient nulls then stable change
+  let seq2: Array<string | null> = [null, null, 'B', 'B']
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B' })
+  const res2 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 3000, pollIntervalMs: 50 })
+  console.log('Test 2: Transient nulls ->', (res2 && (res2 as any).success === true && (res2 as any).newFingerprint === 'B') ? 'PASS' : 'FAIL')
+
+  // Test 3: Timeout
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A' })
+  const res3 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 300, pollIntervalMs: 50 })
+  console.log('Test 3: Timeout ->', (res3 && (res3 as any).success === false && (res3 as any).reason === 'timeout') ? 'PASS' : 'FAIL')
+
+  // Restore original
+  ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = original
+}
+
+runTests().catch(console.error)

package/test/observe/unit/capture_debug_snapshot.test.ts

@@ -0,0 +1,89 @@
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting capture_debug_snapshot unit tests...')
+
+  // Save original ToolsObserve handlers
+  const origCaptureHandler = (ToolsObserve as any).captureScreenshotHandler
+  const origGetCurrentHandler = (ToolsObserve as any).getCurrentScreenHandler
+  const origGetFpHandler = (ToolsObserve as any).getScreenFingerprintHandler
+  const origGetTreeHandler = (ToolsObserve as any).getUITreeHandler
+  const origReadLogStreamHandler = (ToolsObserve as any).readLogStreamHandler
+  const origGetLogsHandler = (ToolsObserve as any).getLogsHandler
+
+  try {
+    // --- Test 1: all components succeed and logs come from stream ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() {
+      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
+    }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function() {
+      return { device: { platform: 'android', id: 'mock' }, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
+    }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+      return { fingerprint: 'abc123', activity: 'Main' }
+    }
+    ;(ToolsObserve as any).getUITreeHandler = async function() {
+      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
+    }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() {
+      return { entries: [ { timestamp: '2026-03-23T20:00:00.000Z', level: 'ERROR', message: 'Boom' } ], crash_summary: { crash_detected: true } }
+    }
+    ;(ToolsObserve as any).getLogsHandler = async function() {
+      return { device: { platform: 'android', id: 'mock' }, logs: [], logCount: 0 }
+    }
+
+    const res1: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 50, sessionId: 's1' })
+    console.log('res1:', JSON.stringify(res1, null, 2))
+    const pass1 = res1 && res1.screenshot === 'BASE64PNG' && res1.activity && res1.fingerprint === 'abc123' && Array.isArray(res1.logs) && res1.logs.length === 1
+    console.log('Test 1:', pass1 ? 'PASS' : 'FAIL')
+
+    // Restore handlers before next test
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+
+    // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { throw new Error('screencap failed') }
+    ;(ToolsObserve as any).getUITreeHandler = async function() { throw new Error('uie_error') }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+    ;(ToolsObserve as any).getLogsHandler = async function() { return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
+
+    const res2: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 10, appId: 'com.example' })
+    console.log('res2:', JSON.stringify(res2, null, 2))
+    const pass2 = res2 && res2.screenshot_error && res2.ui_tree_error && Array.isArray(res2.logs) && res2.logs.length === 2
+    console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
+
+    // Restore handlers before next test
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+
+    // --- Test 3: includeLogs=false should omit logs ---
+    ;(ToolsObserve as any).captureScreenshotHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function() { return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() { return { fingerprint: null } }
+    ;(ToolsObserve as any).getUITreeHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
+    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+
+    const res3: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false })
+    console.log('res3:', JSON.stringify(res3, null, 2))
+    const pass3 = res3 && typeof res3.logs !== 'undefined' && res3.logs.length === 0
+    console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
+
+  } finally {
+    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
+    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
+    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
+    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
+    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
+    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+  }
+}
+
+run().catch(console.error)

package/test/unit/index.ts

@@ -10,5 +10,7 @@ import '../manage/unit/build_and_install.test.ts'
 import '../manage/unit/diagnostics.test.ts'
 import '../manage/unit/detection.test.ts'
 import '../manage/unit/mcp_disable_autodetect.test.ts'
+import '../interact/unit/wait_for_screen_change.test.ts'
+import '../observe/unit/capture_debug_snapshot.test.ts'
 
 console.log('Unit tests loaded.')

package/src/interact/shared/fingerprint.ts

@@ -1,73 +0,0 @@
-import crypto from 'crypto'
-import { GetUITreeResponse, GetCurrentScreenResponse, UIElement } from '../../types.js'
-
-const ANDROID_STRUCTURAL_TYPES = ['Window','Application','View','ViewGroup','LinearLayout','FrameLayout','RelativeLayout','ScrollView','RecyclerView','TextView','ImageView']
-const IOS_STRUCTURAL_TYPES = ['Window','Application','View','ViewController','UITableView','UICollectionView','UILabel','UIImageView','UIView','UIWindow','UIStackView','UITextView','UITableViewCell']
-
-function isDynamicText(t?: string): boolean {
-  if (!t) return false
-  const txt = t.trim()
-  if (!txt) return false
-  if (/\b\d{1,2}:\d{2}\b/.test(txt)) return true
-  if (/\b\d{4}-\d{2}-\d{2}\b/.test(txt)) return true
-  if (/^\d+(?:\.\d+)?%$/.test(txt)) return true
-  if (/^\d+$/.test(txt)) return true
-  if (/^[\d,]{1,10}$/.test(txt)) return true
-  return false
-}
-
-function normalizeElement(e: UIElement) {
-  return {
-    type: (e.type || '').toString(),
-    resourceId: (e.resourceId || '').toString(),
-    text: typeof e.text === 'string' ? (isDynamicText(e.text) ? '' : e.text.trim().toLowerCase()) : '',
-    contentDesc: (e.contentDescription || '').toString(),
-    bounds: Array.isArray(e.bounds) ? e.bounds.slice(0,4).map((n:any)=>Number(n)||0) : [0,0,0,0]
-  }
-}
-
-export function computeScreenFingerprint(tree: GetUITreeResponse, current: GetCurrentScreenResponse | null, platform: 'android' | 'ios', limit: number = 50): { fingerprint: string | null; activity?: string; error?: string } {
-  try {
-    if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
-
-    const activity = current && (current.activity || (current as any).shortActivity) ? (current.activity || (current as any).shortActivity) : ''
-
-    const candidates: UIElement[] = (tree.elements || []).filter(e => {
-      if (!e) return false
-      if (!e.visible) return false
-      const hasStableText = typeof e.text === 'string' && e.text.trim().length > 0
-      const hasResource = !!e.resourceId
-      const interactable = !!e.clickable || !!e.enabled
-      const structuralList = platform === 'android' ? ANDROID_STRUCTURAL_TYPES : IOS_STRUCTURAL_TYPES
-      const structurallySignificant = hasStableText || hasResource || structuralList.includes(e.type || '')
-      return interactable || structurallySignificant
-    }) as UIElement[]
-
-    const normalized = candidates.map(normalizeElement)
-
-    const filteredNormalized = normalized.filter(e => (e.text && e.text.length > 0) || (e.resourceId && e.resourceId.length > 0) || (e.contentDesc && e.contentDesc.length > 0))
-
-    filteredNormalized.sort((a,b) => {
-      const ay = (a.bounds && a.bounds[1]) || 0
-      const by = (b.bounds && b.bounds[1]) || 0
-      if (ay !== by) return ay - by
-      const ax = (a.bounds && a.bounds[0]) || 0
-      const bx = (b.bounds && b.bounds[0]) || 0
-      return ax - bx
-    })
-
-    const limited = filteredNormalized.slice(0, Math.max(0, limit))
-
-    const payload = {
-      activity: platform === 'android' ? (activity || '') : '',
-      resolution: (tree as any).resolution || { width: 0, height: 0 },
-      elements: limited.map(e => ({ type: e.type, resourceId: e.resourceId, text: e.text, contentDesc: e.contentDesc }))
-    }
-
-    const combined = JSON.stringify(payload)
-    const hash = crypto.createHash('sha256').update(combined).digest('hex')
-    return { fingerprint: hash, activity: activity }
-  } catch (e) {
-    return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
-  }
-}