mobile-debug-mcp 0.24.1 → 0.24.2

package/src/types.ts

@@ -10,6 +10,15 @@ export interface StartAppResponse {
   device: DeviceInfo;
   appStarted: boolean;
   launchTimeMs: number;
+  output?: string;
+  observedApp?: {
+    appId: string;
+    package?: string | null;
+    activity?: string | null;
+    screen?: string | null;
+    pid?: number | null;
+    matchedTarget?: boolean | null;
+  };
   error?: string;
   diagnostics?: any;
 }
@@ -25,6 +34,17 @@ export interface RestartAppResponse {
   device: DeviceInfo;
   appRestarted: boolean;
   launchTimeMs: number;
+  output?: string;
+  observedApp?: {
+    appId: string;
+    package?: string | null;
+    activity?: string | null;
+    screen?: string | null;
+    pid?: number | null;
+    matchedTarget?: boolean | null;
+  };
+  terminatedBeforeRestart?: boolean;
+  terminateError?: string;
   error?: string;
   diagnostics?: any;
 }
@@ -155,6 +175,7 @@ export interface ActionExecutionResult {
   action_id: string;
   timestamp: number;
   action_type: string;
+  device?: DeviceInfo;
   target: {
     selector: Record<string, unknown> | null;
     resolved: ActionTargetResolved | null;
@@ -164,6 +185,7 @@ export interface ActionExecutionResult {
   retryable?: boolean;
   ui_fingerprint_before?: string | null;
   ui_fingerprint_after?: string | null;
+  details?: Record<string, unknown>;
 }
 
 export interface TapElementResponse extends ActionExecutionResult {}
@@ -179,6 +201,11 @@ export interface ExpectScreenResponse {
     screen: string | null;
   };
   confidence: number;
+  comparison: {
+    basis: 'fingerprint' | 'screen' | 'none';
+    matched: boolean;
+    reason: string;
+  };
 }
 
 export interface ExpectElementVisibleResponse {
@@ -190,7 +217,16 @@ export interface ExpectElementVisibleResponse {
     contains?: boolean;
   };
   element_id: string | null;
+  expected_condition?: 'visible';
   element?: ActionTargetResolved | null;
+  observed?: {
+    status?: string;
+    matched_count?: number;
+    condition_satisfied?: boolean;
+    selected_index?: number | null;
+    last_matched_element?: ActionTargetResolved | null;
+  };
+  reason?: string;
   failure_code?: 'TIMEOUT' | 'ELEMENT_NOT_FOUND' | 'UNKNOWN';
   retryable?: boolean;
 }

package/test/unit/interact/expect_tools.test.ts

@@ -15,7 +15,12 @@ async function run() {
       success: true,
       observed_screen: { fingerprint: 'fp_home', screen: 'com.example.HomeActivity' },
       expected_screen: { fingerprint: 'fp_home', screen: null },
-      confidence: 1
+      confidence: 1,
+      comparison: {
+        basis: 'fingerprint',
+        matched: true,
+        reason: 'observed fingerprint matches expected fingerprint fp_home'
+      }
     })
 
     ;(Observe as any).ToolsObserve.getCurrentScreenHandler = async () => ({
@@ -26,6 +31,11 @@ async function run() {
     assert.strictEqual(expectScreen.success, true)
     assert.strictEqual(expectScreen.observed_screen.screen, 'HomeActivity')
     assert.strictEqual(expectScreen.confidence, 1)
+    assert.deepStrictEqual(expectScreen.comparison, {
+      basis: 'screen',
+      matched: true,
+      reason: 'observed screen matches expected screen HomeActivity'
+    })
 
     ;(ToolsInteract as any).waitForUIHandler = async () => ({
       status: 'success',
@@ -46,10 +56,18 @@ async function run() {
     assert.strictEqual(expectElementVisible.success, true)
     assert.strictEqual(expectElementVisible.element_id, 'el_ready')
     assert.strictEqual(expectElementVisible.element?.resource_id, 'rid_ready')
+    assert.strictEqual(expectElementVisible.expected_condition, 'visible')
+    assert.strictEqual(expectElementVisible.reason, 'selector is visible')
 
     ;(ToolsInteract as any).waitForUIHandler = async () => ({
       status: 'timeout',
-      error: { code: 'ELEMENT_NOT_FOUND', message: 'Condition visible not satisfied within timeout' }
+      error: { code: 'ELEMENT_NOT_FOUND', message: 'Condition visible not satisfied within timeout; observed 0 match(es)' },
+      observed: {
+        matched_count: 0,
+        condition_satisfied: false,
+        selected_index: null,
+        last_matched_element: null
+      }
     })
     const timeoutResult = await ToolsInteract.expectElementVisibleHandler({
       selector: { text: 'Missing' },
@@ -59,6 +77,15 @@ async function run() {
       success: false,
       selector: { text: 'Missing' },
       element_id: null,
+      expected_condition: 'visible',
+      observed: {
+        status: 'timeout',
+        matched_count: 0,
+        condition_satisfied: false,
+        selected_index: null,
+        last_matched_element: null
+      },
+      reason: 'Condition visible not satisfied within timeout; observed 0 match(es)',
       failure_code: 'TIMEOUT',
       retryable: true
     })

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

@@ -9,22 +9,26 @@ async function runTests() {
 
   try {
     let seq1: Array<string | null> = ['B', 'B']
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq1.length ? seq1.shift() : null, activity: 'MainActivity' })
     const start1 = Date.now()
     const res1 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 2000, pollIntervalMs: 50 })
     const elapsed1 = Date.now() - start1
     assert.ok(res1 && (res1 as any).success === true && (res1 as any).newFingerprint === 'B', 'Immediate fingerprint change should succeed')
+    assert.strictEqual((res1 as any).previousFingerprint, 'A')
+    assert.strictEqual((res1 as any).observed_screen.activity, 'MainActivity')
     console.log('Test 1: Immediate change -> PASS', 'Elapsed:', elapsed1, 'ms')
 
     let seq2: Array<string | null> = [null, null, 'B', 'B']
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B' })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: seq2.length ? seq2.shift() : 'B', activity: 'NextActivity' })
     const res2 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 3000, pollIntervalMs: 50 })
     assert.ok(res2 && (res2 as any).success === true && (res2 as any).newFingerprint === 'B', 'Transient nulls should not prevent success')
     console.log('Test 2: Transient nulls -> PASS')
 
-    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A' })
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = async () => ({ fingerprint: 'A', activity: 'HomeActivity' })
     const res3 = await ToolsInteract.waitForScreenChangeHandler({ platform: 'android', previousFingerprint: 'A', timeoutMs: 300, pollIntervalMs: 50 })
     assert.ok(res3 && (res3 as any).success === false && (res3 as any).reason === 'timeout', 'Unchanged fingerprint should time out')
+    assert.strictEqual((res3 as any).previousFingerprint, 'A')
+    assert.strictEqual((res3 as any).observed_screen.activity, 'HomeActivity')
     console.log('Test 3: Timeout -> PASS')
   } finally {
     ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = original

package/test/unit/interact/wait_for_ui_selector_matching.test.ts

@@ -12,6 +12,12 @@ async function run() {
     const r1 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hello' }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
     const ok1 = r1 && r1.status === 'success' && r1.matched === 1 && r1.element && r1.element.text === 'Hello' && typeof r1.element.elementId === 'string'
     assert.ok(ok1, 'Exact match should satisfy exists condition')
+    assert.deepStrictEqual((r1 as any).requested, {
+      selector: { text: 'Hello' },
+      condition: 'exists',
+      match: null
+    })
+    assert.strictEqual((r1 as any).observed.matched_count, 1)
     console.log('Exact match exists:', ok1 ? 'PASS' : 'FAIL', JSON.stringify(r1, null, 2))
 
     // Test 2: contains matching
@@ -26,6 +32,9 @@ async function run() {
     const r3 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Hidden' }, condition: 'visible', timeout_ms: 300, poll_interval_ms: 50, platform: 'android' })
     const ok3 = r3 && r3.status === 'timeout' && r3.error && r3.error.code === 'ELEMENT_NOT_FOUND'
     assert.ok(ok3, 'Hidden element should fail visible condition')
+    assert.strictEqual((r3 as any).observed.matched_count, 1)
+    assert.strictEqual((r3 as any).observed.condition_satisfied, false)
+    assert.match((r3 as any).error.message, /observed 1 match/)
     console.log('Visible negative (hidden element):', ok3 ? 'PASS' : 'FAIL', JSON.stringify(r3, null, 2))
 
     // Test 4: clickable condition
@@ -66,8 +75,18 @@ async function run() {
     const r7 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, retry: { max_attempts: 1 }, platform: 'android' })
     const ok7 = r7 && r7.status === 'timeout' && r7.error && r7.error.code === 'ELEMENT_NOT_FOUND'
     assert.ok(ok7, 'Missing selector should time out with ELEMENT_NOT_FOUND')
+    assert.strictEqual((r7 as any).observed.selected_index, null)
     console.log('Timeout no match:', ok7 ? 'PASS' : 'FAIL', JSON.stringify(r7, null, 2))
 
+    // Test 8: requested match index out of range should not report a selected index
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OnlyOne', resourceId: 'rid8', bounds: [0,0,10,10], visible: true } ] })
+    const r8 = await ToolsInteract.waitForUIHandler({ selector: { text: 'OnlyOne' }, condition: 'exists', timeout_ms: 300, poll_interval_ms: 50, match: { index: 1 }, platform: 'android' })
+    const ok8 = r8 && r8.status === 'timeout' && r8.error && r8.error.code === 'ELEMENT_NOT_FOUND'
+    assert.ok(ok8, 'Out-of-range match index should time out deterministically')
+    assert.strictEqual((r8 as any).observed.matched_count, 1)
+    assert.strictEqual((r8 as any).observed.selected_index, null)
+    console.log('Out-of-range match index:', ok8 ? 'PASS' : 'FAIL', JSON.stringify(r8, null, 2))
+
   } finally {
     ;(Observe as any).ToolsObserve.getUITreeHandler = origGetUITree
   }

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

@@ -78,38 +78,55 @@ async function run() {
       return {
         device: { platform: 'android', id: 'emulator-5554', osVersion: '14', model: 'Pixel', simulator: true },
         appStarted: true,
-        launchTimeMs: 123
+        launchTimeMs: 123,
+        output: 'Events injected: 1',
+        observedApp: {
+          appId: 'com.example.app',
+          package: 'com.example.app',
+          activity: 'com.example.MainActivity',
+          screen: 'MainActivity',
+          matchedTarget: true
+        }
       } as any
     }
     const startAppResponse = await handleToolCall('start_app', { platform: 'android', appId: 'com.example.app' })
     const startAppPayload = JSON.parse((startAppResponse as any).content[0].text)
     assert.strictEqual(startAppPayload.success, true)
     assert.strictEqual(startAppPayload.action_type, 'start_app')
+    assert.strictEqual(startAppPayload.device.id, 'emulator-5554')
     assert.deepStrictEqual(startAppPayload.target.selector, { appId: 'com.example.app' })
+    assert.strictEqual(startAppPayload.details.launch_time_ms, 123)
+    assert.strictEqual(startAppPayload.details.observed_app.matchedTarget, true)
 
     ;(ToolsInteract as any).expectScreenHandler = async () => ({
       success: true,
       observed_screen: { fingerprint: 'fp_after', screen: 'MainActivity' },
       expected_screen: { fingerprint: 'fp_after', screen: null },
-      confidence: 1
+      confidence: 1,
+      comparison: { basis: 'fingerprint', matched: true, reason: 'observed fingerprint matches expected fingerprint fp_after' }
     })
 
     const expectScreenResponse = await handleToolCall('expect_screen', { fingerprint: 'fp_after' })
     const expectScreenPayload = JSON.parse((expectScreenResponse as any).content[0].text)
     assert.strictEqual(expectScreenPayload.success, true)
     assert.strictEqual(expectScreenPayload.confidence, 1)
+    assert.strictEqual(expectScreenPayload.comparison.basis, 'fingerprint')
 
     ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({
       success: true,
       selector: { text: 'Ready' },
       element_id: 'el_ready',
-      element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 }
+      expected_condition: 'visible',
+      element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 },
+      observed: { status: 'success', matched_count: 1, condition_satisfied: true, selected_index: 0, last_matched_element: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'TextView', bounds: [0, 0, 10, 10], index: 0 } },
+      reason: 'selector is visible'
     })
 
     const expectElementResponse = await handleToolCall('expect_element_visible', { selector: { text: 'Ready' } })
     const expectElementPayload = JSON.parse((expectElementResponse as any).content[0].text)
     assert.strictEqual(expectElementPayload.success, true)
     assert.strictEqual(expectElementPayload.element_id, 'el_ready')
+    assert.strictEqual(expectElementPayload.expected_condition, 'visible')
 
     ;(ToolsObserve as any).captureScreenshotHandler = async () => ({
       device: { platform: 'ios', id: 'booted', osVersion: '18.0', model: 'Simulator', simulator: true },

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

@@ -6,7 +6,9 @@ import { getSystemStatus } from '../../../src/system/index.js'
 async function run() {
   const payload = await getSystemStatus()
   assert(typeof payload.success === 'boolean')
+  assert(typeof (payload as any).status === 'string')
   assert(Array.isArray(payload.issues))
+  assert((payload as any).summary && typeof (payload as any).summary.overall === 'string')
 
   const adb = ensureAdbAvailable()
   assert(adb && typeof adb.ok === 'boolean')

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

@@ -93,8 +93,11 @@ async function run() {
 
     const healthy = await systemStatus.getSystemStatus()
     assert.strictEqual(healthy.success, true)
+    assert.strictEqual((healthy as any).status, 'ready')
     assert.strictEqual(healthy.adbAvailable, true)
     assert.strictEqual(typeof healthy.adbVersion, 'string')
+    assert.strictEqual((healthy as any).summary.android.ready, true)
+    assert.strictEqual(typeof (healthy as any).summary.ios.summary, 'string')
 
     setScenario({
       ADB_VERSION_STATUS: '1',
@@ -105,6 +108,7 @@ async function run() {
     })
     const missingAdb = await systemStatus.getSystemStatus()
     assert.strictEqual(missingAdb.success, false)
+    assert.strictEqual((missingAdb as any).summary.android.ready, false)
     assert(missingAdb.issues.some((issue: string) => issue.includes('ADB')))
 
     setScenario({
@@ -116,6 +120,7 @@ async function run() {
     })
     const unauthorized = await systemStatus.getSystemStatus()
     assert.strictEqual(unauthorized.success, false)
+    assert.strictEqual((unauthorized as any).summary.android.ready, false)
     assert(unauthorized.issues.some((issue: string) => issue.includes('unauthorized')))
     assert(unauthorized.issues.some((issue: string) => issue.includes('offline')))
 
@@ -130,6 +135,7 @@ async function run() {
     assert.strictEqual(missingXcrun.iosAvailable, false)
     assert.strictEqual(missingXcrun.adbAvailable, true)
     assert.strictEqual(Array.isArray(missingXcrun.issues), true)
+    assert.strictEqual((missingXcrun as any).summary.ios.ready, false)
 
     console.log('system_status checks passed')
   } finally {