mobile-debug-mcp 0.21.5 → 0.23.0

package/src/types.ts

@@ -132,6 +132,16 @@ export interface TapResponse {
   error?: string;
 }
 
+export interface TapElementResponse {
+  success: boolean;
+  elementId: string;
+  action: 'tap';
+  error?: {
+    code: 'element_not_found' | 'element_not_visible' | 'element_not_enabled' | 'tap_failed';
+    message: string;
+  };
+}
+
 export interface SwipeResponse {
   device: DeviceInfo;
   success: boolean;
@@ -161,4 +171,3 @@ export interface InstallAppResponse {
   error?: string;
   diagnostics?: any;
 }
-

package/src/utils/resolve-device.ts

@@ -18,14 +18,30 @@ function parseNumericVersion(v: string): number {
   return major + minor / 100
 }
 
+let androidDeviceLister = listAndroidDevices
+let iosDeviceLister = listIOSDevices
+
+export function _setDeviceListersForTests(overrides: {
+  listAndroidDevices?: typeof listAndroidDevices
+  listIOSDevices?: typeof listIOSDevices
+}) {
+  if (overrides.listAndroidDevices) androidDeviceLister = overrides.listAndroidDevices
+  if (overrides.listIOSDevices) iosDeviceLister = overrides.listIOSDevices
+}
+
+export function _resetDeviceListersForTests() {
+  androidDeviceLister = listAndroidDevices
+  iosDeviceLister = listIOSDevices
+}
+
 export async function listDevices(platform?: "android" | "ios", appId?: string): Promise<DeviceInfo[]> {
   if (!platform || platform === "android") {
-    const android = await listAndroidDevices(appId)
+    const android = await androidDeviceLister(appId)
     if (platform === "android") return android
-    const ios = await listIOSDevices(appId)
+    const ios = await iosDeviceLister(appId)
     return [...android, ...ios]
   }
-  return listIOSDevices(appId)
+  return iosDeviceLister(appId)
 }
 
 export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceInfo> {

package/test/device/automated/observe/capture_screenshot.android.smoke.ts

@@ -0,0 +1,30 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping android screenshot smoke test')
+  process.exit(0)
+}
+
+const helperScript = 'test/device/manual/observe/capture_screenshot.manual.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  const out = execSync(`tsx ${helperScript} --platform android --id default`, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed?.resolution || parsed.resolution.width <= 0 || parsed.resolution.height <= 0) throw new Error('Invalid screenshot resolution')
+  if (typeof parsed.screenshotBytes !== 'number' || parsed.screenshotBytes <= 0) throw new Error('Screenshot payload missing')
+
+  log('Android capture_screenshot smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('Android capture_screenshot smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/device/automated/observe/capture_screenshot.ios.smoke.ts

@@ -0,0 +1,30 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping ios screenshot smoke test')
+  process.exit(0)
+}
+
+const helperScript = 'test/device/manual/observe/capture_screenshot.manual.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  const out = execSync(`tsx ${helperScript} --platform ios --id booted`, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed?.resolution || parsed.resolution.width <= 0 || parsed.resolution.height <= 0) throw new Error('Invalid screenshot resolution')
+  if (typeof parsed.screenshotBytes !== 'number' || parsed.screenshotBytes <= 0) throw new Error('Screenshot payload missing')
+
+  log('iOS capture_screenshot smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('iOS capture_screenshot smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/{observe/device → device/automated/observe}/get_logs.android.smoke.ts

@@ -9,7 +9,7 @@ if (process.env.SKIP_DEVICE_TESTS === '1') {
 }
 
 // Ensure helper script exists
-const helperScript = 'test/helpers/run-get-logs.ts'
+const helperScript = 'test/device/manual/observe/get_logs.manual.ts'
 if (!fs.existsSync(helperScript)) {
   console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
   process.exit(1)

package/test/{observe/device → device/automated/observe}/get_logs.ios.smoke.ts

@@ -8,7 +8,7 @@ if (process.env.SKIP_DEVICE_TESTS === '1') {
   process.exit(0)
 }
 
-const helperScript = 'test/helpers/run-get-logs.ts'
+const helperScript = 'test/device/manual/observe/get_logs.manual.ts'
 if (!fs.existsSync(helperScript)) {
   console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
   process.exit(1)

package/test/device/automated/observe/get_ui_tree.android.smoke.ts

@@ -0,0 +1,31 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping android ui tree smoke test')
+  process.exit(0)
+}
+
+const helperScript = 'test/device/manual/observe/get_ui_tree.manual.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  const out = execSync(`tsx ${helperScript} --platform android --id default`, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed?.resolution || parsed.resolution.width <= 0 || parsed.resolution.height <= 0) throw new Error('Invalid UI tree resolution')
+  if (typeof parsed.elementCount !== 'number') throw new Error('elementCount missing')
+  if (parsed.elementCount > 0 && parsed.hasCenterAndDepth !== true) throw new Error('UI element metadata missing center/depth')
+
+  log('Android get_ui_tree smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('Android get_ui_tree smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/device/automated/observe/get_ui_tree.ios.smoke.ts

@@ -0,0 +1,31 @@
+import fs from 'fs'
+import { execSync } from 'child_process'
+
+function log(msg: string) { console.log(msg) }
+
+if (process.env.SKIP_DEVICE_TESTS === '1') {
+  log('SKIP_DEVICE_TESTS=1 detected - skipping ios ui tree smoke test')
+  process.exit(0)
+}
+
+const helperScript = 'test/device/manual/observe/get_ui_tree.manual.ts'
+if (!fs.existsSync(helperScript)) {
+  console.error(`Missing ${helperScript}. Run 'npm run build' first or ensure the helper exists.`)
+  process.exit(1)
+}
+
+try {
+  const out = execSync(`tsx ${helperScript} --platform ios --id booted`, { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024, timeout: 30000 })
+  const parsed = JSON.parse(out)
+
+  if (!parsed?.resolution || parsed.resolution.width <= 0 || parsed.resolution.height <= 0) throw new Error('Invalid UI tree resolution')
+  if (typeof parsed.elementCount !== 'number') throw new Error('elementCount missing')
+  if (parsed.elementCount > 0 && parsed.hasCenterAndDepth !== true) throw new Error('UI element metadata missing center/depth')
+
+  log('iOS get_ui_tree smoke test: PASS')
+  process.exit(0)
+} catch (err: any) {
+  console.error('iOS get_ui_tree smoke test: FAIL')
+  console.error(err && err.message ? err.message : err)
+  process.exit(2)
+}

package/test/device/index.ts

@@ -0,0 +1,52 @@
+import { readdir } from 'fs/promises'
+import path from 'path'
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+
+const deviceRoot = fileURLToPath(new URL('.', import.meta.url))
+const automatedRoot = fileURLToPath(new URL('./automated', import.meta.url))
+const runnableSuffixes = ['.test.ts', '.smoke.ts', '.integration.ts']
+
+async function collectFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = await Promise.all(entries.map(async (entry) => {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) return collectFiles(fullPath)
+    return fullPath
+  }))
+
+  return files.flat()
+}
+
+async function runFile(file: string): Promise<void> {
+  const relativePath = path.relative(deviceRoot, file).replaceAll(path.sep, '/')
+  console.log(`Running device test: ${relativePath}`)
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn('tsx', [file], { stdio: 'inherit' })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`Device test failed: ${relativePath} (exit code ${code ?? 'unknown'})`))
+    })
+  })
+}
+
+(async function () {
+  const allFiles = (await collectFiles(automatedRoot))
+    .filter((file) => runnableSuffixes.some((suffix) => file.endsWith(suffix)))
+    .sort()
+
+  for (const file of allFiles) {
+    await runFile(file)
+  }
+
+  console.log('Device tests loaded.')
+})().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/test/{interact/device/smoke-test.ts → device/manual/interact/app_lifecycle.manual.ts}

@@ -1,6 +1,6 @@
-import { AndroidObserve, iOSObserve } from "../../src/observe/index.js";
-import { AndroidInteract } from "../../src/interact/index.js";
-import { iOSInteract } from "../../src/interact/index.js";
+import { AndroidObserve, iOSObserve } from "../../../src/observe/index.js";
+import { AndroidInteract } from "../../../src/interact/index.js";
+import { iOSInteract } from "../../../src/interact/index.js";
 import fs from "fs/promises";
 
 const androidObserve = new AndroidObserve();
@@ -14,7 +14,7 @@ async function main() {
   const appId = args[1];
 
   if ((platform !== "android" && platform !== "ios") || !appId) {
-    console.error("Usage: npx tsx test/smoke-test.ts <android|ios> <appId>");
+    console.error("Usage: npx tsx test/device/manual/interact/app_lifecycle.manual.ts <android|ios> <appId>");
     process.exit(1);
   }
 
@@ -104,7 +104,7 @@ async function main() {
 
     console.log(`\n✨ Smoke test COMPLETED SUCCESSFULLY! ✨\n`);
 
-  } catch {
+  } catch (error) {
     console.error(`\n❌ Smoke test FAILED:`, error);
     process.exit(1);
   }

package/test/{manage/device/run-build-install-ios.ts → device/manual/manage/build_install_ios.manual.ts}

@@ -35,7 +35,7 @@ function spawnStream(cmd: string, args: string[], opts: any = {}): Promise<numbe
 async function main() {
   const [, , projectPath, deviceId = 'booted'] = process.argv
   if (!projectPath) {
-    console.error('Usage: tsx test/integration/manage/run-build-install-ios.ts <project-dir> [deviceId]')
+    console.error('Usage: tsx test/device/manual/manage/build_install_ios.manual.ts <project-dir> [deviceId]')
     process.exit(1)
   }
 

package/test/{manage/device → device/manual/manage}/install.integration.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-// Integration runner: calls existing run-install-android.ts or run-install-ios.ts
-// Usage: npx tsx test/integration/install.integration.ts /path/to/project [deviceId]
+// Integration runner: calls existing manual install helpers.
+// Usage: npx tsx test/device/manual/manage/install.integration.ts /path/to/project [deviceId]
 import { spawn } from 'child_process'
 import fs from 'fs'
 import path from 'path'
 
 const args = process.argv.slice(2)
 if (args.length < 1) {
-  console.error('Usage: npx tsx test/integration/install.integration.ts /path/to/project [deviceId]')
+  console.error('Usage: npx tsx test/device/manual/manage/install.integration.ts /path/to/project [deviceId]')
   process.exit(2)
 }
 const project = args[0]
@@ -29,9 +29,9 @@ function isIosDir(p: string) {
 
 let runner: string | undefined
 if (isAndroidDir(project)) {
-  runner = path.join(process.cwd(), 'test', 'integration', 'run-install-android.ts')
+  runner = path.join(process.cwd(), 'test', 'device', 'manual', 'manage', 'install_android.manual.ts')
 } else if (isIosDir(project)) {
-  runner = path.join(process.cwd(), 'test', 'integration', 'run-install-ios.ts')
+  runner = path.join(process.cwd(), 'test', 'device', 'manual', 'manage', 'install_ios.manual.ts')
 } else {
   console.error('Cannot determine platform for project:', project)
   process.exit(3)
@@ -39,7 +39,7 @@ if (isAndroidDir(project)) {
 
 if (!runner) process.exit(4)
 
-const proc = spawn('node', [runner, project, ...(deviceId ? [deviceId] : [])], { stdio: ['ignore', 'pipe', 'inherit'] })
+const proc = spawn('tsx', [runner, project, ...(deviceId ? [deviceId] : [])], { stdio: ['ignore', 'pipe', 'inherit'] })
 let stdout = ''
 proc.stdout?.on('data', (c) => { stdout += c.toString() })
 proc.on('close', (code) => {

package/test/{manage/device/run-install-android.ts → device/manual/manage/install_android.manual.ts}

@@ -4,7 +4,7 @@ import { AndroidManage } from '../../../dist/utils/android/manage.js'
 async function main() {
   const [, , appPath, deviceId] = process.argv
   if (!appPath) {
-    console.error('Usage: node test/integration/run-install-android.ts <apk-or-project-dir> [deviceId]')
+    console.error('Usage: node test/device/manual/manage/install_android.manual.ts <apk-or-project-dir> [deviceId]')
     process.exit(1)
   }
 

package/test/{manage/device/run-install-ios.ts → device/manual/manage/install_ios.manual.ts}

@@ -4,7 +4,7 @@ import { iOSManage } from '../../../dist/utils/ios/manage.js'
 async function main() {
   const [, , appPath, deviceId] = process.argv
   if (!appPath) {
-    console.error('Usage: node test/integration/run-install-ios.ts <.app-or-project-dir> [deviceId]')
+    console.error('Usage: node test/device/manual/manage/install_ios.manual.ts <.app-or-project-dir> [deviceId]')
     process.exit(1)
   }
 

package/test/device/manual/observe/capture_screenshot.manual.ts

@@ -0,0 +1,29 @@
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+function readArg(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag)
+  if (index === -1) return undefined
+  return process.argv[index + 1]
+}
+
+async function main() {
+  const platform = (readArg('--platform') || process.argv[2] || 'android') as 'android' | 'ios'
+  const deviceId = readArg('--id') || readArg('--deviceId') || process.argv[3]
+
+  const result = await ToolsObserve.captureScreenshotHandler({ platform, deviceId })
+  const screenshot = (result as any).screenshot || ''
+  const fallback = (result as any).screenshot_fallback || ''
+
+  console.log(JSON.stringify({
+    device: result.device,
+    resolution: result.resolution,
+    mimeType: (result as any).screenshot_mime || 'image/png',
+    screenshotBytes: screenshot ? Buffer.from(screenshot, 'base64').length : 0,
+    fallbackBytes: fallback ? Buffer.from(fallback, 'base64').length : 0
+  }))
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/test/{helpers/run-get-logs.ts → device/manual/observe/get_logs.manual.ts}

@@ -1,4 +1,4 @@
-import { ToolsObserve } from '../../src/observe/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
 import minimist from 'minimist'
 
 async function main() {

package/test/device/manual/observe/get_ui_tree.manual.ts

@@ -0,0 +1,29 @@
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+function readArg(flag: string): string | undefined {
+  const index = process.argv.indexOf(flag)
+  if (index === -1) return undefined
+  return process.argv[index + 1]
+}
+
+async function main() {
+  const platform = (readArg('--platform') || process.argv[2] || 'android') as 'android' | 'ios'
+  const deviceId = readArg('--id') || readArg('--deviceId') || process.argv[3]
+
+  const result = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+  if ((result as any).error) throw new Error((result as any).error)
+
+  const firstElement = Array.isArray((result as any).elements) ? (result as any).elements[0] : null
+
+  console.log(JSON.stringify({
+    device: (result as any).device,
+    resolution: (result as any).resolution,
+    elementCount: Array.isArray((result as any).elements) ? (result as any).elements.length : 0,
+    hasCenterAndDepth: firstElement ? ('center' in firstElement && 'depth' in firstElement) : true
+  }))
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})

package/test/{observe/device/logstream-real.ts → device/manual/observe/logstream.manual.ts}

@@ -1,4 +1,4 @@
-import { AndroidObserve } from '../../src/observe/index.js'
+import { AndroidObserve } from '../../../src/observe/index.js'
 
 async function sleep(ms: number) { return new Promise(r => setTimeout(r, ms)) }
 

package/test/{observe/device/run-screen-fingerprint.ts → device/manual/observe/screen_fingerprint.manual.ts}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Device E2E: get_screen_fingerprint
- * Usage: RUN_DEVICE_TESTS=true npx tsx run-screen-fingerprint.ts [android|ios] [deviceId]
+ * Usage: RUN_DEVICE_TESTS=true npx tsx test/device/manual/observe/screen_fingerprint.manual.ts [android|ios] [deviceId]
  */
 
 import { AndroidObserve } from '../../../src/observe/index.js'

package/test/{observe/device/run-scroll-test-android.ts → device/manual/observe/scroll_to_element_android.manual.ts}

@@ -2,7 +2,7 @@
 import { AndroidInteract } from '../../../dist/interact/index.js'
 
 
-// Usage: tsx test/device/observe/run-scroll-test-android.ts <deviceId> <appId> <selectorText>
+// Usage: tsx test/device/manual/observe/scroll_to_element_android.manual.ts <deviceId> <appId> <selectorText>
 const args = process.argv.slice(2)
 const DEVICE_ID = args[0] || process.env.DEVICE_ID || 'emulator-5554'
 const SELECTOR = args[2] || process.env.SELECTOR || 'Generate Session'

package/test/{observe/device/test-ui-tree.ts → device/manual/observe/ui_tree.manual.ts}

@@ -2,15 +2,15 @@
  * Test script for verify UI Tree functionality.
  * 
  * Usage:
- *   npx tsx test-ui-tree.ts [android|ios] [deviceId]
+ *   npx tsx test/device/manual/observe/ui_tree.manual.ts [android|ios] [deviceId]
  * 
  * Examples:
- *   npx tsx test-ui-tree.ts android
- *   npx tsx test-ui-tree.ts ios booted
+ *   npx tsx test/device/manual/observe/ui_tree.manual.ts android
+ *   npx tsx test/device/manual/observe/ui_tree.manual.ts ios booted
  */
 
-import { AndroidObserve } from '../../src/observe/index.js';
-import { iOSObserve } from '../../src/observe/index.js';
+import { AndroidObserve } from '../../../src/observe/index.js';
+import { iOSObserve } from '../../../src/observe/index.js';
 
 async function main() {
   const args = process.argv.slice(2);
@@ -67,7 +67,7 @@ async function main() {
         console.log(`- Elements with text: ${withText}`);
     }
 
-  } catch {
+  } catch (error) {
     console.error("\n❌ Test Failed:", error);
     process.exit(1);
   }

package/test/unit/index.ts

@@ -1,30 +1,50 @@
-// Aggregator entrypoint for unit tests (updated to new test layout)
-(async function() {
-  // Core unit tests that do not require real devices
-  await import('../observe/unit/logparse.test.ts')
-  await import('../observe/unit/logstream.test.ts')
-  await import('../observe/unit/get_screen_fingerprint.test.ts')
-
-  await import('../manage/unit/install.test.ts')
-  await import('../manage/unit/build.test.ts')
-  await import('../manage/unit/build_and_install.test.ts')
-  await import('../manage/unit/diagnostics.test.ts')
-  await import('../manage/unit/detection.test.ts')
-  await import('../manage/unit/mcp_disable_autodetect.test.ts')
-  await import('../interact/unit/wait_for_screen_change.test.ts')
-
-  // Conditionally include device-dependent unit tests. Set SKIP_DEVICE_TESTS=1 to exclude.
-  if (process.env.SKIP_DEVICE_TESTS !== '1') {
-    try {
-      await import('../observe/unit/capture_debug_snapshot.test.ts')
-      await import('../observe/unit/find_element.test.ts')
-      await import('../interact/unit/wait_for_ui.test.ts')
-    } catch (e) {
-      console.warn('Skipping some device-dependent tests due to import error:', e instanceof Error ? e.message : String(e))
-    }
-  } else {
-    console.log('SKIP_DEVICE_TESTS=1 detected - skipping device-dependent unit tests')
+import { readdir } from 'fs/promises'
+import path from 'path'
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+
+const unitRoot = fileURLToPath(new URL('.', import.meta.url))
+
+async function collectFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files = await Promise.all(entries.map(async (entry) => {
+    const fullPath = path.join(dir, entry.name)
+    if (entry.isDirectory()) return collectFiles(fullPath)
+    return fullPath
+  }))
+
+  return files.flat()
+}
+
+async function runFile(file: string): Promise<void> {
+  const relativePath = path.relative(unitRoot, file).replaceAll(path.sep, '/')
+  console.log(`Running unit test: ${relativePath}`)
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn('tsx', [file], { stdio: 'inherit' })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`Unit test failed: ${relativePath} (exit code ${code ?? 'unknown'})`))
+    })
+  })
+}
+
+(async function () {
+  const allFiles = (await collectFiles(unitRoot))
+    .filter((file) => file.endsWith('.test.ts') && path.basename(file) !== 'index.ts')
+    .sort()
+
+  for (const file of allFiles) {
+    await runFile(file)
   }
 
   console.log('Unit tests loaded.')
-})().catch(e => { console.error(e); process.exit(1) })
+})().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+})