mobile-debug-mcp 0.21.5 → 0.23.0

package/test/unit/interact/classify_action_outcome.test.ts

@@ -0,0 +1,110 @@
+import assert from 'assert'
+import { classifyActionOutcome } from '../../../src/interact/classify.js'
+
+function run() {
+  // Step 1 — uiChanged → success
+  {
+    const result = classifyActionOutcome({ uiChanged: true })
+    assert.strictEqual(result.outcome, 'success')
+    assert.ok(result.reasoning.length > 0)
+    assert.strictEqual(result.nextAction, undefined)
+  }
+
+  // Step 1 — expectedElementVisible → success
+  {
+    const result = classifyActionOutcome({ uiChanged: false, expectedElementVisible: true })
+    assert.strictEqual(result.outcome, 'success')
+    assert.strictEqual(result.reasoning, 'expected element is visible')
+    assert.strictEqual(result.nextAction, undefined)
+  }
+
+  // Step 1 — both uiChanged and expectedElementVisible → success
+  {
+    const result = classifyActionOutcome({ uiChanged: true, expectedElementVisible: true })
+    assert.strictEqual(result.outcome, 'success')
+  }
+
+  // Step 2 — UI did not change, networkRequests not yet provided → nextAction required
+  {
+    const result = classifyActionOutcome({ uiChanged: false })
+    assert.strictEqual(result.outcome, 'unknown')
+    assert.strictEqual(result.nextAction, 'call_get_network_activity')
+  }
+
+  // Step 2 — explicit null networkRequests → nextAction required
+  {
+    const result = classifyActionOutcome({ uiChanged: false, expectedElementVisible: null, networkRequests: null })
+    assert.strictEqual(result.outcome, 'unknown')
+    assert.strictEqual(result.nextAction, 'call_get_network_activity')
+  }
+
+  // Step 3 — failure status → backend_failure
+  {
+    const result = classifyActionOutcome({
+      uiChanged: false,
+      networkRequests: [{ endpoint: '/login', status: 'failure' }]
+    })
+    assert.strictEqual(result.outcome, 'backend_failure')
+    assert.ok(result.reasoning.includes('/login'))
+    assert.ok(result.reasoning.includes('failure'))
+  }
+
+  // Step 3 — retryable status → backend_failure
+  {
+    const result = classifyActionOutcome({
+      uiChanged: false,
+      networkRequests: [
+        { endpoint: '/api/submit', status: 'retryable' },
+        { endpoint: '/api/other', status: 'success' }
+      ]
+    })
+    assert.strictEqual(result.outcome, 'backend_failure')
+    assert.ok(result.reasoning.includes('/api/submit'))
+  }
+
+  // Step 4 — empty network requests → no_op
+  {
+    const result = classifyActionOutcome({ uiChanged: false, networkRequests: [] })
+    assert.strictEqual(result.outcome, 'no_op')
+    assert.ok(result.reasoning.includes('no UI change'))
+    assert.ok(result.reasoning.includes('no network activity'))
+  }
+
+  // Step 4 — empty network requests with log errors → no_op with note
+  {
+    const result = classifyActionOutcome({ uiChanged: false, networkRequests: [], hasLogErrors: true })
+    assert.strictEqual(result.outcome, 'no_op')
+    assert.ok(result.reasoning.includes('log errors'))
+  }
+
+  // Step 5 — all requests succeeded but UI unchanged → ui_failure
+  {
+    const result = classifyActionOutcome({
+      uiChanged: false,
+      networkRequests: [
+        { endpoint: '/api/save', status: 'success' },
+        { endpoint: '/api/refresh', status: 'success' }
+      ]
+    })
+    assert.strictEqual(result.outcome, 'ui_failure')
+    assert.ok(result.reasoning.includes('network requests succeeded'))
+  }
+
+  // Step 1 takes priority over network signals — success even when failures present
+  {
+    const result = classifyActionOutcome({
+      uiChanged: true,
+      networkRequests: [{ endpoint: '/api/log', status: 'failure' }]
+    })
+    assert.strictEqual(result.outcome, 'success')
+  }
+
+  console.log('classify_action_outcome tests passed')
+}
+
+try {
+  run()
+} catch (error) {
+  console.error(error)
+  process.exit(1)
+}

package/test/unit/interact/handler_shapes.test.ts

@@ -0,0 +1,55 @@
+import assert from 'assert'
+import { ToolsInteract, AndroidInteract } from '../../../src/interact/index.js'
+
+async function run() {
+  const originalMockDevices = process.env.MCP_TEST_MOCK_DEVICES
+  const originalTap = AndroidInteract.prototype.tap
+  const originalScrollToElement = AndroidInteract.prototype.scrollToElement
+
+  process.env.MCP_TEST_MOCK_DEVICES = '1'
+
+  try {
+    AndroidInteract.prototype.tap = async function (x: number, y: number, deviceId?: string) {
+      return {
+        device: { platform: 'android', id: deviceId || 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+        success: true,
+        x,
+        y
+      } as any
+    }
+
+    const tapResponse = await ToolsInteract.tapHandler({ platform: 'android', x: 10, y: 20 })
+    assert.strictEqual(tapResponse.success, true)
+    assert.strictEqual(typeof tapResponse.device.id, 'string')
+    assert.strictEqual(tapResponse.x, 10)
+    assert.strictEqual(tapResponse.y, 20)
+
+    AndroidInteract.prototype.scrollToElement = async function () {
+      return {
+        success: true,
+        element: { text: 'Settings', bounds: [0, 0, 100, 50] },
+        scrollsPerformed: 2
+      } as any
+    }
+
+    const scrollResponse = await ToolsInteract.scrollToElementHandler({
+      platform: 'android',
+      selector: { text: 'Settings' }
+    })
+    assert.strictEqual(scrollResponse.success, true)
+    assert.strictEqual(scrollResponse.scrollsPerformed, 2)
+    assert.strictEqual(scrollResponse.element.text, 'Settings')
+
+    console.log('interact handler shape tests passed')
+  } finally {
+    AndroidInteract.prototype.tap = originalTap
+    AndroidInteract.prototype.scrollToElement = originalScrollToElement
+    if (typeof originalMockDevices === 'undefined') delete process.env.MCP_TEST_MOCK_DEVICES
+    else process.env.MCP_TEST_MOCK_DEVICES = originalMockDevices
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/interact/tap_element.test.ts

@@ -0,0 +1,170 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+
+async function run() {
+  console.log('Starting tap_element unit tests...')
+  const originalGetUITreeHandler = (Observe as any).ToolsObserve.getUITreeHandler
+  const originalTapHandler = (ToolsInteract as any).tapHandler
+  const originalComputeElementId = (ToolsInteract as any)._computeElementId
+  ;(ToolsInteract as any)._resetResolvedUiElementsForTests()
+
+  try {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Submit', resourceId: 'btn_submit', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true }
+      ]
+    })
+
+    const waitSuccess = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Submit' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    assert.strictEqual(waitSuccess.status, 'success')
+    const successElementId = waitSuccess.element.elementId
+
+    let tapped: { x: number, y: number, platform?: string, deviceId?: string } | null = null
+    ;(ToolsInteract as any).tapHandler = async ({ platform, x, y, deviceId }: any) => {
+      tapped = { platform, x, y, deviceId }
+      return { success: true, device: { platform: platform || 'android', id: deviceId || 'mock-device' }, x, y }
+    }
+
+    const tapSuccess = await ToolsInteract.tapElementHandler({ elementId: successElementId })
+    assert.deepStrictEqual(tapSuccess, { success: true, elementId: successElementId, action: 'tap' })
+    assert.deepStrictEqual(tapped, { platform: 'android', x: 10, y: 10, deviceId: 'mock-device' })
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Hidden', resourceId: 'btn_hidden', bounds: [0, 0, 20, 20], visible: false, enabled: true, clickable: true }
+      ]
+    })
+    const waitHidden = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Hidden' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    const hiddenResult = await ToolsInteract.tapElementHandler({ elementId: waitHidden.element.elementId })
+    assert.strictEqual(hiddenResult.success, false)
+    assert.strictEqual(hiddenResult.error?.code, 'element_not_visible')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Disabled', resourceId: 'btn_disabled', bounds: [0, 0, 20, 20], visible: true, enabled: false, clickable: true }
+      ]
+    })
+    const waitDisabled = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Disabled' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    const disabledResult = await ToolsInteract.tapElementHandler({ elementId: waitDisabled.element.elementId })
+    assert.strictEqual(disabledResult.success, false)
+    assert.strictEqual(disabledResult.error?.code, 'element_not_enabled')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: []
+    })
+    const notFoundResult = await ToolsInteract.tapElementHandler({ elementId: successElementId })
+    assert.strictEqual(notFoundResult.success, false)
+    assert.strictEqual(notFoundResult.error?.code, 'element_not_found')
+
+    ;(ToolsInteract as any)._resetResolvedUiElementsForTests()
+    const targetIndex = 25
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: Array.from({ length: 50 }, (_, index) => ({
+        text: index === targetIndex ? 'Indexed target' : `Filler ${index}`,
+        resourceId: index === targetIndex ? 'btn_indexed_target' : `btn_filler_${index}`,
+        bounds: [index, index, index + 20, index + 20],
+        visible: true,
+        enabled: true,
+        clickable: true
+      }))
+    })
+    const indexedWait = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Indexed target' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    assert.strictEqual(indexedWait.status, 'success')
+
+    let computeCalls = 0
+    ;(ToolsInteract as any)._computeElementId = (...args: any[]) => {
+      computeCalls++
+      return originalComputeElementId.apply(ToolsInteract, args)
+    }
+    const indexedTap = await ToolsInteract.tapElementHandler({ elementId: indexedWait.element.elementId })
+    assert.strictEqual(indexedTap.success, true)
+    assert.strictEqual(computeCalls, 1, 'Stored index should allow a single fast-path element ID check')
+    ;(ToolsInteract as any)._computeElementId = originalComputeElementId
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: Array.from({ length: 51 }, (_, index) => ({
+        text: index === 0 ? 'Inserted first' : index === targetIndex + 1 ? 'Indexed target' : `Shifted filler ${index}`,
+        resourceId: index === 0 ? 'btn_inserted_first' : index === targetIndex + 1 ? 'btn_indexed_target' : `btn_shifted_filler_${index}`,
+        bounds: [index, index, index + 20, index + 20],
+        visible: true,
+        enabled: true,
+        clickable: true
+      }))
+    })
+    const shiftedIndexResult = await ToolsInteract.tapElementHandler({ elementId: indexedWait.element.elementId })
+    assert.strictEqual(shiftedIndexResult.success, false)
+    assert.strictEqual(shiftedIndexResult.error?.code, 'element_not_found')
+
+    ;(ToolsInteract as any)._resetResolvedUiElementsForTests()
+    const cacheLimit = (ToolsInteract as any)._maxResolvedUiElements as number
+    let oldestElementId: string | null = null
+    let cacheFixtureIndex = 0
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: `Button ${cacheFixtureIndex}`, resourceId: `btn_${cacheFixtureIndex}`, bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true }
+      ]
+    })
+
+    for (let i = 0; i < cacheLimit + 1; i++) {
+      cacheFixtureIndex = i
+      const result = await ToolsInteract.waitForUIHandler({
+        selector: { text: `Button ${i}` },
+        condition: 'exists',
+        timeout_ms: 200,
+        poll_interval_ms: 50,
+        platform: 'android'
+      })
+      assert.strictEqual(result.status, 'success')
+      if (i === 0) oldestElementId = result.element.elementId
+    }
+
+    assert.ok(oldestElementId, 'Oldest element ID should be captured')
+    const evictedResult = await ToolsInteract.tapElementHandler({ elementId: oldestElementId as string })
+    assert.strictEqual(evictedResult.success, false)
+    assert.strictEqual(evictedResult.error?.code, 'element_not_found')
+
+    console.log('tap_element unit tests passed')
+  } finally {
+    ;(ToolsInteract as any)._resetResolvedUiElementsForTests()
+    ;(ToolsInteract as any)._computeElementId = originalComputeElementId
+    ;(Observe as any).ToolsObserve.getUITreeHandler = originalGetUITreeHandler
+    ;(ToolsInteract as any).tapHandler = originalTapHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

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

@@ -0,0 +1,34 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+import assert from 'assert'
+
+const original = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+async function runTests() {
+  console.log('Starting tests for wait_for_screen_change...')
+
+  try {
+    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
+    assert.ok(res1 && (res1 as any).success === true && (res1 as any).newFingerprint === 'B', 'Immediate fingerprint change should succeed')
+    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' })
+    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' })
+    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')
+    console.log('Test 3: Timeout -> PASS')
+  } finally {
+    ;(Observe as any).ToolsObserve.getScreenFingerprintHandler = original
+  }
+}
+
+runTests().catch((error) => { console.error(error); process.exit(1) })

package/test/{interact/unit → unit/interact}/wait_for_ui_contract.test.ts

@@ -8,21 +8,22 @@ async function run() {
 
   try {
     // success shape
-    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OK', resourceId: 'rid', contentDescription: 'acc', type: 'TextView', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'OK', resourceId: 'rid', contentDescription: 'acc', type: 'TextView', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
     const s = await ToolsInteract.waitForUIHandler({ selector: { text: 'OK' }, condition: 'exists', timeout_ms: 500, poll_interval_ms: 50, platform: 'android' })
     // Assert contract fields for success
-    assert.strictEqual(s.status, 'success', 'status must be success')
-    assert.strictEqual(typeof s.matched, 'number', 'matched must be number')
-    assert.ok(s.element, 'element must be present')
-    assert.ok(s.metrics && typeof s.metrics.latency_ms === 'number' && typeof s.metrics.poll_count === 'number' && typeof s.metrics.attempts === 'number', 'metrics must include latency_ms, poll_count, attempts')
-    assert.ok(['string','object'].includes(typeof s.element.bounds) || Array.isArray(s.element.bounds), 'element.bounds must be present')
+    assert.strictEqual(s.status, 'success', 'status must be success');
+    assert.strictEqual(typeof s.matched, 'number', 'matched must be number');
+    assert.ok(s.element, 'element must be present');
+    assert.strictEqual(typeof s.element.elementId, 'string', 'elementId must be present');
+    assert.ok(s.metrics && typeof s.metrics.latency_ms === 'number' && typeof s.metrics.poll_count === 'number' && typeof s.metrics.attempts === 'number', 'metrics must include latency_ms, poll_count, attempts');
+    assert.ok(typeof s.element.bounds !== 'undefined' && s.element.bounds !== null, 'element.bounds must be present');
 
     // timeout shape
-    (Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
     const t = await ToolsInteract.waitForUIHandler({ selector: { text: 'Nope' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, platform: 'android' })
-    assert.strictEqual(t.status, 'timeout', 'status must be timeout on no match')
-    assert.ok(t.error && t.error.code && t.error.message, 'timeout must include error with code and message')
-    assert.ok(t.metrics && typeof t.metrics.latency_ms === 'number', 'timeout metrics must include latency_ms')
+    assert.strictEqual(t.status, 'timeout', 'status must be timeout on no match');
+    assert.ok(t.error && t.error.code && t.error.message, 'timeout must include error with code and message');
+    assert.ok(t.metrics && typeof t.metrics.latency_ms === 'number', 'timeout metrics must include latency_ms');
 
     console.log('wait_for_ui contract tests: PASS')
   } finally {

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

@@ -0,0 +1,76 @@
+import { ToolsInteract } from '../../../src/interact/index.js'
+import * as Observe from '../../../src/observe/index.js'
+import assert from 'assert'
+
+async function run() {
+  console.log('Starting new wait_for_ui unit tests...')
+  const origGetUITree = (Observe as any).ToolsObserve.getUITreeHandler
+
+  try {
+    // Test 1: exact text match -> exists
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hello', resourceId: 'rid1', contentDescription: 'acc1', type: 'Button', bounds: [0,0,10,10], visible: true, clickable: false, enabled: true } ] })
+    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')
+    console.log('Exact match exists:', ok1 ? 'PASS' : 'FAIL', JSON.stringify(r1, null, 2))
+
+    // Test 2: contains matching
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Welcome User', resourceId: 'rid2', contentDescription: 'acc2', type: 'TextView', bounds: [0,0,50,10], visible: true } ] })
+    const r2 = await ToolsInteract.waitForUIHandler({ selector: { text: 'User', contains: true }, condition: 'exists', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok2 = r2 && r2.status === 'success' && r2.matched === 1 && r2.element && r2.element.text && r2.element.text.includes('Welcome') && typeof r2.element.elementId === 'string'
+    assert.ok(ok2, 'Contains matching should succeed')
+    console.log('Contains match:', ok2 ? 'PASS' : 'FAIL', JSON.stringify(r2, null, 2))
+
+    // Test 3: visible condition
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'Hidden', resourceId: 'rid3', bounds: [0,0,0,0], visible: false } ] })
+    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')
+    console.log('Visible negative (hidden element):', ok3 ? 'PASS' : 'FAIL', JSON.stringify(r3, null, 2))
+
+    // Test 4: clickable condition
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [ { text: 'TapMe', resourceId: 'rid4', bounds: [0,0,20,20], visible: true, clickable: true, enabled: true } ] })
+    const r4 = await ToolsInteract.waitForUIHandler({ selector: { text: 'TapMe' }, condition: 'clickable', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok4 = r4 && r4.status === 'success' && r4.matched === 1 && r4.element && r4.element.index === 0 && typeof r4.element.elementId === 'string'
+    assert.ok(ok4, 'Clickable element should satisfy clickable condition')
+    console.log('Clickable match:', ok4 ? 'PASS' : 'FAIL', JSON.stringify(r4, null, 2))
+
+    // Test 5: clickable condition should resolve a clickable parent for matching text
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      elements: [
+        { bounds: [100, 100, 300, 220], visible: true, clickable: true, enabled: true, children: [1] },
+        { text: 'Play session', bounds: [140, 130, 260, 180], visible: true, clickable: false, enabled: true, parentId: 0 }
+      ]
+    })
+    const r5 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Play Session', contains: true }, condition: 'clickable', timeout_ms: 1000, poll_interval_ms: 50, platform: 'android' })
+    const ok5 = r5 && r5.status === 'success' && r5.element && r5.element.index === 0
+    assert.ok(ok5, 'Clickable parent should satisfy clickable condition for child label text')
+    console.log('Clickable parent resolution:', ok5 ? 'PASS' : 'FAIL', JSON.stringify(r5, null, 2))
+
+    // Test 6: retry behavior - first attempt times out, second attempt succeeds
+    const start = Date.now()
+    let seqTree = async () => {
+      const now = Date.now()
+      // for first ~400ms return no elements, afterwards return match
+      if (now - start < 400) return { elements: [] }
+      return { elements: [ { text: 'Retried', resourceId: 'rid5', bounds: [0,0,10,10], visible: true } ] }
+    }
+    ;(Observe as any).ToolsObserve.getUITreeHandler = seqTree
+    const r6 = await ToolsInteract.waitForUIHandler({ selector: { text: 'Retried' }, condition: 'exists', timeout_ms: 200, poll_interval_ms: 50, match: undefined, retry: { max_attempts: 3, backoff_ms: 150 }, platform: 'android' })
+    const ok6 = r6 && r6.status === 'success' && r6.metrics && r6.metrics.attempts >= 2
+    assert.ok(ok6, 'Retry path should eventually succeed')
+    console.log('Retry behavior:', ok6 ? 'PASS' : 'FAIL', JSON.stringify(r6, null, 2))
+
+    // Test 7: timeout with no selector match -> correct error code
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({ elements: [] })
+    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')
+    console.log('Timeout no match:', ok7 ? 'PASS' : 'FAIL', JSON.stringify(r7, null, 2))
+
+  } finally {
+    ;(Observe as any).ToolsObserve.getUITreeHandler = origGetUITree
+  }
+}
+
+run().catch(err => { console.error('wait_for_ui_selector_matching tests failed:', err); process.exit(1) })

package/test/unit/manage/handler_shapes.test.ts

@@ -0,0 +1,43 @@
+import assert from 'assert'
+import { ToolsManage } from '../../../src/manage/index.js'
+
+async function run() {
+  const originalBuildAppHandler = (ToolsManage as any).buildAppHandler
+  const originalInstallAppHandler = (ToolsManage as any).installAppHandler
+
+  try {
+    ;(ToolsManage as any).buildAppHandler = async () => ({ artifactPath: '/tmp/fake.apk' })
+    ;(ToolsManage as any).installAppHandler = async () => ({
+      device: { platform: 'android', id: 'emulator-5554', osVersion: '14', model: 'Pixel', simulator: true },
+      installed: true,
+      output: 'Installed'
+    })
+
+    const response = await ToolsManage.buildAndInstallHandler({
+      platform: 'android',
+      projectPath: '/tmp/project',
+      projectType: 'native'
+    })
+
+    const lines = response.ndjson.trim().split('\n').map((line) => JSON.parse(line))
+    assert.deepStrictEqual(lines.map((line) => `${line.type}:${line.status}`), [
+      'build:started',
+      'build:finished',
+      'install:started',
+      'install:finished'
+    ])
+    assert.strictEqual(response.result.success, true)
+    assert.strictEqual((response.result as any).artifactPath, '/tmp/fake.apk')
+    assert.strictEqual((response.result as any).device.id, 'emulator-5554')
+
+    console.log('manage handler shape tests passed')
+  } finally {
+    ;(ToolsManage as any).buildAppHandler = originalBuildAppHandler
+    ;(ToolsManage as any).installAppHandler = originalInstallAppHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})