mobile-debug-mcp 0.21.5 → 0.22.0

package/test/unit/observe/scroll_to_element.test.ts

@@ -0,0 +1,127 @@
+import { AndroidInteract } from '../../../src/interact/index.js'
+import assert from 'assert'
+
+async function runTests() {
+  console.log = (...args: any[]) => { try { process.stdout.write(args.map(a => (typeof a === 'string' ? a : JSON.stringify(a))).join(' ') + '\n') } catch {} }
+  console.log('Starting tests for scroll_to_element...')
+
+  const ai = new AndroidInteract()
+  const origObserveGet = ai['observe'].getUITree
+  const origSwipe = ai.swipe
+
+  try {
+    console.log('\nTest 1: Element found immediately')
+    ;(ai['observe'] as any).getUITree = async () => ({
+      device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: [{
+        text: 'Target',
+        type: 'Button',
+        contentDescription: null,
+        clickable: true,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 100, 100],
+        resourceId: null
+      }]
+    })
+
+    const res1 = await ai.scrollToElement({ text: 'Target' }, 'down', 5, 0.7, 'mock')
+    assert.strictEqual(res1.success, true, 'Element visible on first screen should be found immediately')
+    console.log('Result: PASS')
+    console.log('scrollsPerformed:', (res1 as any).scrollsPerformed)
+
+    console.log('\nTest 2: Element found after scrolling')
+    let calls = 0
+    ;(ai['observe'] as any).getUITree = async () => {
+      calls++
+      if (calls < 3) {
+        return {
+          device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+          screen: '',
+          resolution: { width: 1080, height: 1920 },
+          elements: [{
+            text: `Placeholder ${calls}`,
+            type: 'TextView',
+            contentDescription: null,
+            clickable: false,
+            enabled: true,
+            visible: true,
+            bounds: [0, calls * 10, 100, calls * 10 + 20],
+            resourceId: `placeholder-${calls}`
+          }]
+        }
+      }
+
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [{
+          text: 'Target',
+          type: 'Button',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 100, 100],
+          resourceId: null
+        }]
+      }
+    }
+    ;(ai as any).swipe = async () => ({ success: true })
+
+    const res2 = await ai.scrollToElement({ text: 'Target' }, 'down', 5, 0.7, 'mock')
+    assert.strictEqual(res2.success, true, 'Element found after scrolling should succeed')
+    assert.ok(calls >= 3, 'scroll_to_element should retry until the target appears')
+    console.log('Result: PASS')
+    console.log('calls:', calls)
+
+    console.log('\nTest 3: UI unchanged stops early')
+    ;(ai['observe'] as any).getUITree = async () => ({
+      device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 1920 },
+      elements: []
+    })
+    ;(ai as any).swipe = async () => ({ success: true })
+
+    const res3 = await ai.scrollToElement({ text: 'Missing' }, 'down', 5, 0.7, 'mock')
+    assert.ok(res3.success === false && (res3 as any).scrollsPerformed === 1, 'Unchanged UI should stop early after the first unchanged scroll')
+    console.log('Result: PASS')
+    console.log('Reason:', (res3 as any).reason || JSON.stringify(res3))
+
+    console.log('\nTest 4: Offscreen element scrolls into view')
+    let swiped = false
+    let swipeCalled = 0
+    ;(ai['observe'] as any).getUITree = async () => {
+      if (!swiped) {
+        return {
+          device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+          screen: '',
+          resolution: { width: 1080, height: 1920 },
+          elements: [{ text: null, type: 'android.view.View', resourceId: null, contentDescription: null, bounds: [0, 0, 1080, 200], visible: true }]
+        }
+      }
+
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [{ text: 'OffscreenTarget', type: 'android.widget.Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [100, 400, 300, 460], resourceId: null }]
+      }
+    }
+    ;(ai as any).swipe = async () => { swipeCalled++; swiped = true; return { success: true } }
+
+    const res4 = await ai.scrollToElement({ text: 'OffscreenTarget' }, 'down', 3, 0.7, 'mock')
+    assert.ok(res4 && (res4 as any).success === true && (res4 as any).scrollsPerformed === 1 && swipeCalled === 1, 'Offscreen target should be found after one swipe')
+    console.log('Result: PASS')
+    console.log('  success:', (res4 as any).success, 'scrollsPerformed:', (res4 as any).scrollsPerformed, 'swipeCalled:', swipeCalled)
+  } finally {
+    ;(ai['observe'] as any).getUITree = origObserveGet
+    ;(ai as any).swipe = origSwipe
+  }
+}
+
+runTests().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/server/contract.test.ts

@@ -0,0 +1,45 @@
+import assert from 'assert'
+import { handleToolCall, serverInfo, toolDefinitions } from '../../../src/server-core.js'
+
+async function run() {
+  const names = toolDefinitions.map((tool) => tool.name)
+  const uniqueNames = new Set(names)
+
+  assert.strictEqual(serverInfo.name, 'mobile-debug-mcp')
+  assert.strictEqual(names.length, uniqueNames.size, 'tool names should be unique')
+  assert(names.includes('wait_for_ui'))
+  assert(names.includes('capture_screenshot'))
+  assert(names.includes('get_ui_tree'))
+  assert(names.includes('tap_element'))
+
+  const waitForUI = toolDefinitions.find((tool) => tool.name === 'wait_for_ui')
+  assert(waitForUI, 'wait_for_ui should be registered')
+  assert.strictEqual((waitForUI as any).inputSchema.properties.timeout_ms.default, 60000)
+  assert.strictEqual((waitForUI as any).inputSchema.properties.condition.default, 'exists')
+
+  const captureDebugSnapshot = toolDefinitions.find((tool) => tool.name === 'capture_debug_snapshot')
+  assert(captureDebugSnapshot, 'capture_debug_snapshot should be registered')
+  assert.strictEqual((captureDebugSnapshot as any).inputSchema.properties.includeLogs.default, true)
+  assert.strictEqual((captureDebugSnapshot as any).inputSchema.properties.logLines.default, 200)
+
+  const startLogStream = toolDefinitions.find((tool) => tool.name === 'start_log_stream')
+  assert(startLogStream, 'start_log_stream should be registered')
+  assert.strictEqual((startLogStream as any).inputSchema.properties.platform.default, 'android')
+
+  const startApp = toolDefinitions.find((tool) => tool.name === 'start_app')
+  assert(startApp, 'start_app should be registered')
+  assert.deepStrictEqual((startApp as any).inputSchema.required, ['platform', 'appId'])
+
+  const tapElement = toolDefinitions.find((tool) => tool.name === 'tap_element')
+  assert(tapElement, 'tap_element should be registered')
+  assert.deepStrictEqual((tapElement as any).inputSchema.required, ['elementId'])
+
+  await assert.rejects(() => handleToolCall('unknown_tool'), /Unknown tool: unknown_tool/)
+
+  console.log('server contract tests passed')
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/server/response_shapes.test.ts

@@ -0,0 +1,93 @@
+import assert from 'assert'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsManage } from '../../../src/manage/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  const originalInstallAppHandler = (ToolsManage as any).installAppHandler
+  const originalWaitForUIHandler = (ToolsInteract as any).waitForUIHandler
+  const originalTapElementHandler = (ToolsInteract as any).tapElementHandler
+  const originalCaptureScreenshotHandler = (ToolsObserve as any).captureScreenshotHandler
+  const originalGetUITreeHandler = (ToolsObserve as any).getUITreeHandler
+
+  try {
+    ;(ToolsManage as any).installAppHandler = async () => ({
+      device: { platform: 'android', id: 'emulator-5554', osVersion: '14', model: 'Pixel', simulator: true },
+      installed: true,
+      output: 'Success'
+    })
+
+    const installResponse = await handleToolCall('install_app', { platform: 'android', projectType: 'native', appPath: '/tmp/app.apk' })
+    assert.strictEqual((installResponse as any).content.length, 1)
+    const installPayload = JSON.parse((installResponse as any).content[0].text)
+    assert.strictEqual(installPayload.installed, true)
+    assert.strictEqual(installPayload.output, 'Success')
+    assert.strictEqual(installPayload.device.id, 'emulator-5554')
+
+    ;(ToolsInteract as any).waitForUIHandler = async () => ({
+      status: 'success',
+      matched: 1,
+      element: { text: 'Ready', bounds: [0, 0, 10, 10], index: 0, elementId: 'el_ready' },
+      metrics: { latency_ms: 12, poll_count: 1, attempts: 1 }
+    })
+
+    const waitForUIResponse = await handleToolCall('wait_for_ui', { selector: { text: 'Ready' } })
+    const waitForUIPayload = JSON.parse((waitForUIResponse as any).content[0].text)
+    assert.strictEqual(waitForUIPayload.status, 'success')
+    assert.strictEqual(waitForUIPayload.metrics.poll_count, 1)
+    assert.strictEqual(waitForUIPayload.element.text, 'Ready')
+    assert.strictEqual(waitForUIPayload.element.elementId, 'el_ready')
+
+    ;(ToolsInteract as any).tapElementHandler = async () => ({
+      success: true,
+      elementId: 'el_ready',
+      action: 'tap'
+    })
+
+    const tapElementResponse = await handleToolCall('tap_element', { elementId: 'el_ready' })
+    const tapElementPayload = JSON.parse((tapElementResponse as any).content[0].text)
+    assert.strictEqual(tapElementPayload.success, true)
+    assert.strictEqual(tapElementPayload.elementId, 'el_ready')
+    assert.strictEqual(tapElementPayload.action, 'tap')
+
+    ;(ToolsObserve as any).captureScreenshotHandler = async () => ({
+      device: { platform: 'ios', id: 'booted', osVersion: '18.0', model: 'Simulator', simulator: true },
+      screenshot: Buffer.from('png-data').toString('base64'),
+      screenshot_mime: 'image/png',
+      resolution: { width: 390, height: 844 }
+    })
+
+    const screenshotResponse = await handleToolCall('capture_screenshot', { platform: 'ios' })
+    assert.strictEqual((screenshotResponse as any).content.length, 2)
+    const screenshotMeta = JSON.parse((screenshotResponse as any).content[0].text)
+    assert.strictEqual((screenshotResponse as any).content[1].type, 'image')
+    assert.strictEqual((screenshotResponse as any).content[1].mimeType, 'image/png')
+    assert.strictEqual(screenshotMeta.result.resolution.width, 390)
+
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+      resolution: { width: 1080, height: 2400 },
+      elements: [{ text: 'Login', depth: 0, center: { x: 50, y: 20 } }]
+    })
+
+    const uiTreeResponse = await handleToolCall('get_ui_tree', { platform: 'android' })
+    const uiTreePayload = JSON.parse((uiTreeResponse as any).content[0].text)
+    assert.strictEqual(uiTreePayload.elements.length, 1)
+    assert.strictEqual(uiTreePayload.resolution.height, 2400)
+    assert.strictEqual(uiTreePayload.elements[0].text, 'Login')
+
+    console.log('server response-shape tests passed')
+  } finally {
+    ;(ToolsManage as any).installAppHandler = originalInstallAppHandler
+    ;(ToolsInteract as any).waitForUIHandler = originalWaitForUIHandler
+    ;(ToolsInteract as any).tapElementHandler = originalTapElementHandler
+    ;(ToolsObserve as any).captureScreenshotHandler = originalCaptureScreenshotHandler
+    ;(ToolsObserve as any).getUITreeHandler = originalGetUITreeHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/system/adb_version.test.ts

@@ -0,0 +1,35 @@
+import assert from 'assert'
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+import * as systemStatus from '../../../src/system/index.js'
+
+async function run() {
+  const binDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-system-adb-'))
+  const adbPath = path.join(binDir, 'adb')
+  const originalAdbPath = process.env.ADB_PATH
+
+  try {
+    await fs.writeFile(adbPath, `#!/bin/sh
+if [ "$1" = "--version" ]; then
+  printf 'Android Debug Bridge version 1.0.41\nRevision 8f3b7\n'
+  exit 0
+fi
+if [ "$1" = "devices" ]; then
+  printf 'List of devices attached\n'
+  exit 0
+fi
+exit 0
+`, { mode: 0o755 })
+    process.env.ADB_PATH = adbPath
+    const res = await systemStatus.getSystemStatus()
+    assert.strictEqual(res.adbVersion, 'Android Debug Bridge version 1.0.41')
+    console.log('adb version parsing test passed')
+  } finally {
+    if (originalAdbPath === undefined) delete process.env.ADB_PATH
+    else process.env.ADB_PATH = originalAdbPath
+    await fs.rm(binDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/system/get_system_status.test.ts

@@ -0,0 +1,20 @@
+import assert from 'assert'
+import { ensureAdbAvailable } from '../../../src/utils/android/utils.js'
+import { getXcrunCmd } from '../../../src/utils/ios/utils.js'
+import { getSystemStatus } from '../../../src/system/index.js'
+
+async function run() {
+  const payload = await getSystemStatus()
+  assert(typeof payload.success === 'boolean')
+  assert(Array.isArray(payload.issues))
+
+  const adb = ensureAdbAvailable()
+  assert(adb && typeof adb.ok === 'boolean')
+
+  const cmd = getXcrunCmd()
+  assert(typeof cmd === 'string')
+
+  console.log('get_system_status unit tests passed')
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/system/system_status.test.ts

@@ -0,0 +1,141 @@
+import assert from 'assert'
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+
+import * as systemStatus from '../../../src/system/index.js'
+
+async function writeFakeCommands(binDir: string) {
+  const adbPath = path.join(binDir, 'adb')
+  const xcrunPath = path.join(binDir, 'xcrun')
+
+  await fs.writeFile(adbPath, `#!/bin/sh
+if [ "$1" = "--version" ]; then
+  if [ "\${ADB_VERSION_STATUS:-0}" != "0" ]; then
+    printf '%s' "\${ADB_VERSION_OUTPUT:-not found}" >&2
+    exit "\${ADB_VERSION_STATUS}"
+  fi
+  printf '%s' "\${ADB_VERSION_OUTPUT:-Android Debug Bridge version 8.1.0}"
+  exit 0
+fi
+if [ "$1" = "devices" ]; then
+  printf '%s' "\${ADB_DEVICES_OUTPUT:-List of devices attached}"
+  exit 0
+fi
+if [ "$1" = "logcat" ]; then
+  printf '%s' "\${ADB_LOGCAT_OUTPUT:-I/Tag: ok}"
+  exit 0
+fi
+if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "path" ]; then
+  printf '%s' "\${ADB_PM_PATH_OUTPUT:-package:/data/app/com.example/base.apk}"
+  exit 0
+fi
+printf '%s' "\${ADB_DEFAULT_OUTPUT:-OK}"
+exit 0
+`, { mode: 0o755 })
+
+  await fs.writeFile(xcrunPath, `#!/bin/sh
+if [ "$1" = "--version" ]; then
+  if [ "\${XCRUN_VERSION_STATUS:-0}" != "0" ]; then
+    printf '%s' "\${XCRUN_VERSION_OUTPUT:-not found}" >&2
+    exit "\${XCRUN_VERSION_STATUS}"
+  fi
+  printf '%s' "\${XCRUN_VERSION_OUTPUT:-xcrun version 123}"
+  exit 0
+fi
+if [ "$1" = "simctl" ] && [ "$2" = "list" ] && [ "$3" = "devices" ] && [ "$4" = "booted" ] && [ "$5" = "--json" ]; then
+  printf '%s' "\${SIMCTL_LIST_OUTPUT:-{\"devices\":{}}}"
+  exit 0
+fi
+printf '%s' "\${XCRUN_DEFAULT_OUTPUT:-ok}"
+exit 0
+`, { mode: 0o755 })
+
+  return { adbPath, xcrunPath }
+}
+
+function setScenario(env: Record<string, string | undefined>) {
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete process.env[key]
+    else process.env[key] = value
+  }
+}
+
+async function run() {
+  const binDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-system-status-'))
+  const originalEnv = {
+    ADB_PATH: process.env.ADB_PATH,
+    XCRUN_PATH: process.env.XCRUN_PATH,
+    ADB_VERSION_OUTPUT: process.env.ADB_VERSION_OUTPUT,
+    ADB_VERSION_STATUS: process.env.ADB_VERSION_STATUS,
+    ADB_DEVICES_OUTPUT: process.env.ADB_DEVICES_OUTPUT,
+    ADB_LOGCAT_OUTPUT: process.env.ADB_LOGCAT_OUTPUT,
+    ADB_PM_PATH_OUTPUT: process.env.ADB_PM_PATH_OUTPUT,
+    XCRUN_VERSION_OUTPUT: process.env.XCRUN_VERSION_OUTPUT,
+    XCRUN_VERSION_STATUS: process.env.XCRUN_VERSION_STATUS,
+    SIMCTL_LIST_OUTPUT: process.env.SIMCTL_LIST_OUTPUT,
+  }
+
+  try {
+    const { adbPath, xcrunPath } = await writeFakeCommands(binDir)
+    process.env.ADB_PATH = adbPath
+    process.env.XCRUN_PATH = xcrunPath
+
+    setScenario({
+      ADB_VERSION_STATUS: '0',
+      ADB_VERSION_OUTPUT: '8.1.0\n',
+      ADB_DEVICES_OUTPUT: 'List of devices attached\nemulator-5554\tdevice product:sdk\n',
+      ADB_LOGCAT_OUTPUT: 'I/Tag: ok\n',
+      XCRUN_VERSION_STATUS: '0',
+      XCRUN_VERSION_OUTPUT: 'xcrun version 123\n',
+      SIMCTL_LIST_OUTPUT: JSON.stringify({ devices: { runtime: [{ state: 'Booted' }] } }),
+    })
+
+    const healthy = await systemStatus.getSystemStatus()
+    assert.strictEqual(healthy.success, true)
+    assert.strictEqual(healthy.adbAvailable, true)
+    assert.strictEqual(typeof healthy.adbVersion, 'string')
+
+    setScenario({
+      ADB_VERSION_STATUS: '1',
+      ADB_VERSION_OUTPUT: 'not found',
+      ADB_DEVICES_OUTPUT: 'List of devices attached\n',
+      XCRUN_VERSION_STATUS: '0',
+      XCRUN_VERSION_OUTPUT: 'xcrun version\n',
+    })
+    const missingAdb = await systemStatus.getSystemStatus()
+    assert.strictEqual(missingAdb.success, false)
+    assert(missingAdb.issues.some((issue: string) => issue.includes('ADB')))
+
+    setScenario({
+      ADB_VERSION_STATUS: '0',
+      ADB_VERSION_OUTPUT: '8.1.0\n',
+      ADB_DEVICES_OUTPUT: 'List of devices attached\nserial1\tunauthorized\nserial2\toffline\n',
+      XCRUN_VERSION_STATUS: '0',
+      XCRUN_VERSION_OUTPUT: 'xcrun version\n',
+    })
+    const unauthorized = await systemStatus.getSystemStatus()
+    assert.strictEqual(unauthorized.success, false)
+    assert(unauthorized.issues.some((issue: string) => issue.includes('unauthorized')))
+    assert(unauthorized.issues.some((issue: string) => issue.includes('offline')))
+
+    setScenario({
+      ADB_VERSION_STATUS: '0',
+      ADB_VERSION_OUTPUT: '8.1.0\n',
+      ADB_DEVICES_OUTPUT: 'List of devices attached\nemulator-5554\tdevice product:sdk\n',
+      XCRUN_VERSION_STATUS: '1',
+      XCRUN_VERSION_OUTPUT: 'not found',
+    })
+    const missingXcrun = await systemStatus.getSystemStatus()
+    assert.strictEqual(missingXcrun.iosAvailable, false)
+    assert.strictEqual(missingXcrun.adbAvailable, true)
+    assert.strictEqual(Array.isArray(missingXcrun.issues), true)
+
+    console.log('system_status checks passed')
+  } finally {
+    setScenario(originalEnv)
+    await fs.rm(binDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/{utils → unit/utils}/detect_java.test.ts

@@ -1,6 +1,6 @@
 import fs from 'fs'
 import path from 'path'
-import { detectJavaHome } from '../../src/utils/java.js'
+import { detectJavaHome } from '../../../src/utils/java.js'
 
 async function run() {
   // Create a temporary fake JDK that reports Java 17

package/test/unit/utils/exec.test.ts

@@ -0,0 +1,51 @@
+import assert from 'assert'
+import fs from 'fs/promises'
+import os from 'os'
+import path from 'path'
+import { execAdbWithDiagnostics } from '../../../src/utils/diagnostics.js'
+import { execCmd } from '../../../src/utils/exec.js'
+
+async function run() {
+  const envResult = await execCmd(process.execPath, ['-e', 'console.log(process.env.MCP_EXEC_TEST); console.error("warn");'], {
+    env: { MCP_EXEC_TEST: 'hello' }
+  })
+  assert.strictEqual(envResult.exitCode, 0)
+  assert.strictEqual(envResult.stdout, 'hello')
+  assert.strictEqual(envResult.stderr, 'warn')
+
+  const timeoutResult = await execCmd(process.execPath, ['-e', 'setTimeout(() => console.log("late"), 200)'], {
+    timeout: 50
+  })
+  assert.strictEqual(timeoutResult.exitCode, null)
+  assert.strictEqual(timeoutResult.stdout, '')
+
+  const binDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-exec-adb-'))
+  const adbPath = path.join(binDir, 'adb')
+  const script = `#!/bin/sh
+echo "device not found" >&2
+exit 1
+`
+  const originalAdbPath = process.env.ADB_PATH
+
+  try {
+    await fs.writeFile(adbPath, script, { mode: 0o755 })
+    process.env.ADB_PATH = adbPath
+
+    const adbResult = execAdbWithDiagnostics(['shell', 'getprop'], 'emulator-5554')
+    assert.strictEqual(adbResult.runResult.command, adbPath)
+    assert.deepStrictEqual(adbResult.runResult.args.slice(0, 2), ['-s', 'emulator-5554'])
+    assert.match(adbResult.runResult.stderr, /device not found/)
+    assert(adbResult.runResult.suggestedFixes?.some((fix) => fix.includes('adb devices')))
+
+    console.log('exec utility tests passed')
+  } finally {
+    if (typeof originalAdbPath === 'undefined') delete process.env.ADB_PATH
+    else process.env.ADB_PATH = originalAdbPath
+    await fs.rm(binDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/utils/resolve_device.test.ts

@@ -0,0 +1,63 @@
+import assert from 'assert'
+import {
+  listDevices,
+  resolveTargetDevice,
+  _setDeviceListersForTests,
+  _resetDeviceListersForTests
+} from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  try {
+    _setDeviceListersForTests({
+      listAndroidDevices: async () => ([
+        { id: 'android-1', platform: 'android', osVersion: '14', model: 'Pixel 8', simulator: true },
+        { id: 'android-2', platform: 'android', osVersion: '13', model: 'Pixel 7', simulator: false, appInstalled: true } as any
+      ]),
+      listIOSDevices: async () => ([
+        { id: 'ios-1', platform: 'ios', osVersion: '18.0', model: 'iPhone 15', simulator: true, booted: false } as any,
+        { id: 'ios-2', platform: 'ios', osVersion: '17.4', model: 'iPhone 14', simulator: true, booted: true } as any
+      ])
+    })
+
+    const combined = await listDevices()
+    assert.strictEqual(combined.length, 4)
+
+    const explicit = await resolveTargetDevice({ platform: 'android', deviceId: 'android-1' })
+    assert.strictEqual(explicit.id, 'android-1')
+
+    const preferredPhysical = await resolveTargetDevice({ platform: 'android', prefer: 'physical' })
+    assert.strictEqual(preferredPhysical.id, 'android-2')
+
+    const installedForApp = await resolveTargetDevice({ platform: 'android', appId: 'com.example.app' })
+    assert.strictEqual(installedForApp.id, 'android-2')
+
+    const bootedIOS = await resolveTargetDevice({ platform: 'ios' })
+    assert.strictEqual(bootedIOS.id, 'ios-2')
+
+    _setDeviceListersForTests({
+      listAndroidDevices: async () => ([
+        { id: 'android-a', platform: 'android', osVersion: '14.0', model: 'Pixel 8', simulator: false },
+        { id: 'android-b', platform: 'android', osVersion: '14.0', model: 'Pixel 8 Pro', simulator: false }
+      ])
+    })
+
+    await assert.rejects(
+      () => resolveTargetDevice({ platform: 'android' }),
+      (error: unknown) => {
+        assert(error instanceof Error)
+        assert.match(error.message, /Multiple matching devices found/)
+        assert.strictEqual(Array.isArray((error as any).devices), true)
+        return true
+      }
+    )
+
+    console.log('resolve-device tests passed')
+  } finally {
+    _resetDeviceListersForTests()
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/tsconfig.json

@@ -9,6 +9,6 @@
     "skipLibCheck": true,
     "esModuleInterop": true
   },
-  "exclude": ["smoke-test.ts", "test-ui-tree.ts", "test/**/*.ts"],
+  "exclude": ["test/**/*.ts"],
   "include": ["src/**/*"]
-}
+}

package/test/interact/device/run-real-test.ts

@@ -1,3 +0,0 @@
-// wait_for_element device runner removed
-console.log('wait_for_element device runner removed');
-process.exit(0);

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

@@ -1,32 +0,0 @@
-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)