mobile-debug-mcp 0.21.5 → 0.22.0

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)
+})

package/test/{observe/unit → unit/observe}/capture_debug_snapshot.test.ts

@@ -1,4 +1,5 @@
 import { ToolsObserve } from '../../../src/observe/index.js'
+import assert from 'assert'
 
 async function run() {
   console.log('Starting capture_debug_snapshot unit tests...')
@@ -35,6 +36,7 @@ async function run() {
     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
+    assert.ok(pass1, 'captureDebugSnapshot should aggregate successful handler results')
     console.log('Test 1:', pass1 ? 'PASS' : 'FAIL')
 
     // Restore handlers before next test
@@ -54,6 +56,7 @@ async function run() {
     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
+    assert.ok(pass2, 'captureDebugSnapshot should surface partial failures and fallback logs')
     console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
 
     // Restore handlers before next test
@@ -74,6 +77,7 @@ async function run() {
     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
+    assert.ok(pass3, 'captureDebugSnapshot should return an empty logs array when includeLogs is false')
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
   } finally {
@@ -86,4 +90,4 @@ async function run() {
   }
 }
 
-run().catch(console.error)
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/{observe/unit → unit/observe}/find_element.test.ts

@@ -1,5 +1,6 @@
 import { ToolsInteract } from '../../../src/interact/index.js'
 import { ToolsObserve } from '../../../src/observe/index.js'
+import assert from 'assert'
 
 async function run() {
   process.stdout.write('Starting find_element unit tests...\n')
@@ -8,7 +9,7 @@ async function run() {
 
   try {
     // Test 1: exact text match
-    (ToolsObserve as any).getUITreeHandler = async () => ({
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock' },
       screen: '',
       resolution: { width: 1080, height: 1920 },
@@ -21,10 +22,11 @@ async function run() {
     const res1: any = await ToolsInteract.findElementHandler({ query: 'login', exact: true, platform: 'android' })
     process.stdout.write('res1 ' + JSON.stringify(res1, null, 2) + '\n');
     const pass1 = res1.found === true && res1.element && res1.element.resourceId === 'btn_login' && res1.element.tapCoordinates && typeof res1.element.tapCoordinates.x === 'number' && typeof res1.element.tapCoordinates.y === 'number' && typeof res1.confidence === 'number'
+    assert.ok(pass1, 'Exact text match should find the actionable login button')
     process.stdout.write('Test 1: ' + (pass1 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 2: partial match & scoring
-    (ToolsObserve as any).getUITreeHandler = async () => ({
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock' },
       screen: '',
       resolution: { width: 1080, height: 1920 },
@@ -37,10 +39,11 @@ async function run() {
     const res2: any = await ToolsInteract.findElementHandler({ query: 'login', exact: false, platform: 'android' })
     process.stdout.write('res2 ' + JSON.stringify(res2, null, 2) + '\n');
     const pass2 = res2.found === true && res2.element && res2.element.resourceId === 'btn_login_email' && res2.element.tapCoordinates && typeof res2.element.tapCoordinates.x === 'number' && typeof res2.element.tapCoordinates.y === 'number' && typeof res2.confidence === 'number'
+    assert.ok(pass2, 'Partial text matching should pick the best scoring element')
     process.stdout.write('Test 2: ' + (pass2 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 3: resourceId match
-    (ToolsObserve as any).getUITreeHandler = async () => ({
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock' },
       screen: '',
       resolution: { width: 1080, height: 1920 },
@@ -52,10 +55,11 @@ async function run() {
     const res3: any = await ToolsInteract.findElementHandler({ query: 'icon_login', exact: false, platform: 'android' })
     process.stdout.write('res3 ' + JSON.stringify(res3, null, 2) + '\n');
     const pass3 = res3.found === true && res3.element && res3.element.resourceId === 'icon_login' && res3.element.tapCoordinates && typeof res3.element.tapCoordinates.x === 'number' && typeof res3.element.tapCoordinates.y === 'number' && typeof res3.confidence === 'number'
+    assert.ok(pass3, 'Resource-id matching should find icon_login')
     process.stdout.write('Test 3: ' + (pass3 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 4: parent-clickable child-text scenario
-    (ToolsObserve as any).getUITreeHandler = async () => ({
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock' },
       screen: '',
       resolution: { width: 1080, height: 1920 },
@@ -68,13 +72,15 @@ async function run() {
     const res4: any = await ToolsInteract.findElementHandler({ query: 'generate', exact: false, platform: 'android', timeoutMs: 300 })
     process.stdout.write('res4 ' + JSON.stringify(res4, null, 2) + '\n');
     const pass4 = res4.found === true && res4.element && res4.element.clickable === true && res4.element.resourceId === 'btn_generate' && res4.element.tapCoordinates && typeof res4.element.tapCoordinates.x === 'number' && typeof res4.element.tapCoordinates.y === 'number' && typeof res4.confidence === 'number'
+    assert.ok(pass4, 'Child text should resolve to a clickable parent ancestor')
     process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 5: not found
-    (ToolsObserve as any).getUITreeHandler = async () => ({ device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] })
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({ device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] })
     const res5: any = await ToolsInteract.findElementHandler({ query: 'nope', exact: false, platform: 'android', timeoutMs: 300 })
     process.stdout.write('res5 ' + JSON.stringify(res5, null, 2) + '\n');
     const pass5 = res5.found === false
+    assert.ok(pass5, 'Missing elements should return found=false')
     process.stdout.write('Test 5: ' + (pass5 ? 'PASS' : 'FAIL') + '\n');
 
   } finally {
@@ -82,4 +88,4 @@ async function run() {
   }
 }
 
-run().catch(console.error)
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/observe/get_screen_fingerprint.test.ts

@@ -0,0 +1,71 @@
+import { AndroidObserve } from '../../../src/observe/index.js'
+import assert from 'assert'
+
+async function run() {
+  console.log('Starting get_screen_fingerprint unit tests...')
+
+  const origGet = (AndroidObserve as any).prototype.getUITree
+  const origCurrent = (AndroidObserve as any).prototype.getCurrentScreen
+
+  try {
+    ;(AndroidObserve as any).prototype.getUITree = async function() {
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [
+          { text: 'Title', type: 'TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [0,0,1080,100], resourceId: 'id/title' },
+          { text: 'Sign in', type: 'Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,200,200,260], resourceId: 'id/signin' }
+        ]
+      }
+    }
+
+    ;(AndroidObserve as any).prototype.getCurrentScreen = async function() {
+      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, package: 'com.example', activity: 'com.example.MainActivity', shortActivity: 'MainActivity' }
+    }
+
+    const ai = new AndroidObserve()
+    const a = await ai.getScreenFingerprint('mock')
+    const b = await ai.getScreenFingerprint('mock')
+    assert.strictEqual(a.fingerprint, b.fingerprint, 'Identical screens should produce the same fingerprint')
+    console.log('Test 1: PASS')
+
+    ;(AndroidObserve as any).prototype.getUITree = async function() {
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [
+          { text: 'Title', type: 'TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [0,0,1080,100], resourceId: 'id/title' },
+          { text: 'Profile', type: 'Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,200,200,260], resourceId: 'id/signin' }
+        ]
+      }
+    }
+
+    const c = await ai.getScreenFingerprint('mock')
+    assert.notStrictEqual(a.fingerprint, c.fingerprint, 'Meaningful UI text changes should change the fingerprint')
+    console.log('Test 2: PASS')
+
+    ;(AndroidObserve as any).prototype.getUITree = async function() {
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true },
+        screen: '',
+        resolution: { width: 1080, height: 1920 },
+        elements: [
+          { text: 'Title', type: 'TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [0,0,1080,100], resourceId: 'id/title' },
+          { text: 'Sign in', type: 'Button', contentDescription: null, clickable: true, enabled: true, visible: true, bounds: [0,200,200,260], resourceId: 'id/signin' },
+          { text: '12:34', type: 'TextView', contentDescription: null, clickable: false, enabled: true, visible: true, bounds: [900,10,1080,40], resourceId: null }
+        ]
+      }
+    }
+
+    const d = await ai.getScreenFingerprint('mock')
+    assert.strictEqual(a.fingerprint, d.fingerprint, 'Dynamic timestamp-like text should be ignored')
+    console.log('Test 3: PASS')
+  } finally {
+    ;(AndroidObserve as any).prototype.getUITree = origGet
+    ;(AndroidObserve as any).prototype.getCurrentScreen = origCurrent
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/observe/ios-getlogs.test.ts

@@ -0,0 +1,53 @@
+import { iOSObserve, _resetIOSExecCommandForTests, _setIOSExecCommandForTests } from '../../../src/observe/ios'
+import assert from 'assert'
+
+function stubExecCommand(expectedArgsChecker: (args: string[]) => boolean, output: string) {
+  return async function (args: string[], deviceId?: string) {
+    if (!expectedArgsChecker(args)) throw new Error('Unexpected args: ' + JSON.stringify(args))
+    return { output, device: { platform: 'ios', id: deviceId || 'booted' } }
+  }
+}
+
+async function run() {
+  const bundle = 'com.ideamechanics.modul8'
+  const pgrepOutput = '12345\n'
+  const logOutput = '2026-03-31 09:21:20.085 Module[12345:678] <Info> Modul8: Test message'
+
+  try {
+    const obs = new iOSObserve()
+    _setIOSExecCommandForTests(stubExecCommand((args) => args.includes('pgrep'), pgrepOutput))
+
+    let called = false
+    _setIOSExecCommandForTests(async function (args: string[]) {
+      if (args.includes('pgrep')) return { output: pgrepOutput, device: { platform: 'ios', id: 'booted' } }
+      if (args.includes('log') && args.includes('show')) {
+        called = true
+        return { output: logOutput, device: { platform: 'ios', id: 'booted' } }
+      }
+      throw new Error('Unexpected args: ' + JSON.stringify(args))
+    })
+
+    const pidResult = await obs.getLogs({ appId: bundle, deviceId: 'booted' })
+    assert(pidResult.meta.processNameUsed === 'modul8' || pidResult.meta.processNameUsed === 'Modul8' || !!pidResult.meta.processNameUsed)
+    assert(pidResult.meta.detectedPid === 12345)
+    assert(pidResult.source === 'pid')
+    assert(pidResult.logCount === 1)
+    assert(pidResult.logs[0].message.includes('Test message'))
+    assert(called, 'log show must have been called')
+
+    _setIOSExecCommandForTests(async function (args: string[]) {
+      if (args.includes('log') && args.includes('show')) return { output: '2026-03-31 09:21:20.085 SomeOther[222:333] <Info> Other: Hello', device: { platform: 'ios', id: 'booted' } }
+      throw new Error('Unexpected args: ' + JSON.stringify(args))
+    })
+
+    const broadResult = await new iOSObserve().getLogs({ deviceId: 'booted' })
+    assert(broadResult.source === 'broad')
+    assert(broadResult.logCount === 1)
+
+    console.log('iOS getLogs predicate and meta tests passed')
+  } finally {
+    _resetIOSExecCommandForTests()
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })