mobile-debug-mcp 0.21.5 → 0.23.0

package/test/unit/network/get_network_activity.test.ts

@@ -0,0 +1,181 @@
+import assert from 'assert'
+import {
+  parseMessageToEvent,
+  normalizeEndpoint,
+  classifyStatus,
+  _setTimestampsForTests,
+  ToolsNetwork
+} from '../../../src/network/index.js'
+
+function run() {
+
+  // ─── normalizeEndpoint ──────────────────────────────────────────────────────
+
+  {
+    const r = normalizeEndpoint('https://api.example.com/v1/users?page=2')
+    assert.strictEqual(r, '/v1/users', `normalizeEndpoint full URL: expected /v1/users, got ${r}`)
+  }
+
+  {
+    const r = normalizeEndpoint('/api/login/')
+    assert.strictEqual(r, '/api/login', `normalizeEndpoint path trailing slash: expected /api/login, got ${r}`)
+  }
+
+  {
+    const r = normalizeEndpoint('/Api/Login')
+    assert.strictEqual(r, '/api/login', `normalizeEndpoint uppercase: expected /api/login, got ${r}`)
+  }
+
+  // ─── classifyStatus ─────────────────────────────────────────────────────────
+
+  {
+    const s = classifyStatus(200, null)
+    assert.strictEqual(s, 'success', `200 should be success`)
+  }
+
+  {
+    const s = classifyStatus(404, null)
+    assert.strictEqual(s, 'failure', `404 should be failure`)
+  }
+
+  {
+    const s = classifyStatus(500, null)
+    assert.strictEqual(s, 'retryable', `500 should be retryable`)
+  }
+
+  {
+    const s = classifyStatus(null, 'timeout')
+    assert.strictEqual(s, 'retryable', `networkError should override to retryable`)
+  }
+
+  {
+    const s = classifyStatus(200, 'connection_reset')
+    assert.strictEqual(s, 'retryable', `networkError beats statusCode`)
+  }
+
+  {
+    const s = classifyStatus(null, null)
+    assert.strictEqual(s, 'success', `null/null (request detected, no error) = success`)
+  }
+
+  // ─── parseMessageToEvent — emission criteria ─────────────────────────────────
+
+  // Condition 1: full URL
+  {
+    const e = parseMessageToEvent('OkHttp: GET https://api.example.com/v1/login 200')
+    assert.ok(e !== null, 'full URL line should emit')
+    assert.strictEqual(e!.endpoint, '/v1/login')
+    assert.strictEqual(e!.method, 'GET')
+    assert.strictEqual(e!.statusCode, 200)
+    assert.strictEqual(e!.status, 'success')
+  }
+
+  // Condition 2: explicit HTTP status line
+  {
+    const e = parseMessageToEvent('HTTP/1.1 404 Not Found')
+    assert.ok(e !== null, 'HTTP status line should emit')
+    assert.strictEqual(e!.statusCode, 404)
+    assert.strictEqual(e!.status, 'failure')
+  }
+
+  // Condition 3: method + path
+  {
+    const e = parseMessageToEvent('Sending POST /api/register HTTP/1.1')
+    assert.ok(e !== null, 'method+path line should emit')
+    assert.strictEqual(e!.method, 'POST')
+    assert.strictEqual(e!.endpoint, '/api/register')
+    assert.strictEqual(e!.statusCode, null)
+    assert.strictEqual(e!.status, 'success') // no error signal
+  }
+
+  // No criteria met — keyword-only noise
+  {
+    const e = parseMessageToEvent('HTTP connection pool initialised')
+    assert.strictEqual(e, null, 'keyword-only line should not emit')
+  }
+
+  {
+    const e = parseMessageToEvent('Request interceptor registered')
+    assert.strictEqual(e, null, 'generic Request line should not emit')
+  }
+
+  {
+    const e = parseMessageToEvent('Task 200 completed')
+    assert.strictEqual(e, null, 'bare status-like numbers should not emit')
+  }
+
+  {
+    const e = parseMessageToEvent('Response code: 404')
+    assert.strictEqual(e, null, 'labeled status without endpoint or HTTP context should not emit')
+  }
+
+  {
+    const e = parseMessageToEvent('GetBestInfo: /data/app/~~pkg/base.apk status=447')
+    assert.strictEqual(e, null, 'filesystem paths should not emit as network endpoints')
+  }
+
+  {
+    const e = parseMessageToEvent('system/gd/hci/le_address_manager.cc:576 GetNextPrivateAddressIntervalRange')
+    assert.strictEqual(e, null, 'source file paths should not emit as network endpoints')
+  }
+
+  {
+    const e = parseMessageToEvent('status=503 for /api/session/generate')
+    assert.ok(e !== null, 'status with plausible endpoint should emit')
+    assert.strictEqual(e!.endpoint, '/api/session/generate')
+    assert.strictEqual(e!.statusCode, 503)
+    assert.strictEqual(e!.status, 'retryable')
+  }
+
+  // Network error detection
+  {
+    const e = parseMessageToEvent('java.net.SocketTimeoutException: POST /api/data timed out after 30s')
+    assert.ok(e !== null, 'timeout error should emit')
+    assert.strictEqual(e!.networkError, 'timeout')
+    assert.strictEqual(e!.status, 'retryable')
+  }
+
+  {
+    const e = parseMessageToEvent('SSL handshake failed for https://api.example.com/v1/auth')
+    assert.ok(e !== null, 'TLS error should emit')
+    assert.strictEqual(e!.networkError, 'tls_error')
+    assert.strictEqual(e!.status, 'retryable')
+  }
+
+  {
+    const e = parseMessageToEvent('DNS resolution failed: GET /api/users')
+    assert.ok(e !== null, 'DNS error should emit')
+    assert.strictEqual(e!.networkError, 'dns_error')
+    assert.strictEqual(e!.status, 'retryable')
+  }
+
+  // 5xx → retryable even without networkError
+  {
+    const e = parseMessageToEvent('Response 503 for https://api.example.com/v1/data')
+    assert.ok(e !== null, '5xx should emit')
+    assert.strictEqual(e!.statusCode, 503)
+    assert.strictEqual(e!.status, 'retryable')
+  }
+
+  // ─── lastConsumedTimestamp dedupe ────────────────────────────────────────────
+
+  {
+    // Simulate: action happened 1000ms ago, last consumed 500ms ago → use consumed
+    _setTimestampsForTests(Date.now() - 1000, Date.now() - 500)
+    // We can't easily verify the sinceMs value from outside without deep mocking,
+    // but we can confirm getNetworkActivity resolves without throwing.
+    const promise = ToolsNetwork.getNetworkActivity({ platform: 'android' })
+    assert.ok(promise instanceof Promise, 'getNetworkActivity should return a Promise')
+    // Allow the promise to settle (logcat may fail in test env — that's fine)
+    promise.catch(() => {})
+  }
+
+  console.log('get_network_activity tests passed')
+}
+
+try {
+  run()
+} catch (err) {
+  console.error(err)
+  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) })

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

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

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

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