mobile-debug-mcp 0.35.0 → 0.37.0

package/test/unit/server/readiness.test.ts

@@ -1,3 +1,4 @@
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
 import assert from 'node:assert/strict'
 import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv'
 import { handleToolCall, toolDefinitions } from '../../../src/server-core.js'
@@ -10,6 +11,7 @@ async function run() {
   const originalTree = ToolsObserve.getUITreeHandler
   const originalNative = AndroidObserve.prototype.getUITree
   const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+  let deviceState = 'unknown'
   let reads = 0
   let mode = 'stable'
   let delayed = 0
@@ -43,12 +45,33 @@ async function run() {
     queueMicrotask(() => { elapsed += Math.max(0, Number(delay) || 0); callback(...args) })
     return {} as ReturnType<typeof setTimeout>
   }) as typeof setTimeout
-  const call = async (name: string, args: any = {}) => JSON.parse((await handleToolCall(name, { platform: 'android', deviceId: 'fixture', ...args })).content[0].text!)
+  const call = async (name: string, args: any = {}) => withDeviceReadinessProbe(async (_cmd, nativeArgs) => {
+    const power = 'mWakefulness=Awake\nmWakefulnessChanging=false'
+    const keyguard = `KeyguardServiceDelegate\n showing=${deviceState === 'locked'}\n mIsShowing=${deviceState === 'locked'}`
+    return { exitCode: 0, stdout: deviceState === 'unknown' ? '' : nativeArgs.includes('power') ? power : keyguard, stderr: '' }
+  }, async () => JSON.parse((await handleToolCall(name, { platform: 'android', deviceId: 'fixture', ...args })).content[0].text!))
   try {
     let result = await call('get_app_readiness', { stabilityMs: 100 })
     assert.equal(result.readiness.state, 'settled')
     assert.equal(result.success, true)
     assert.equal(reads, 2)
+    deviceState = 'locked'; reads = 0
+    result = await call('get_app_readiness')
+    assert.deepEqual(result.device_readiness.blockers, ['DEVICE_LOCKED'])
+    assert.equal(result.success, true, 'an observed blocker is a successful observation')
+    assert.equal(reads, 0, 'known blocker avoids a slow UI read')
+    result = await call('wait_for_app_ready', { timeoutMs: 300, pollIntervalMs: 100 })
+    assert.equal(result.success, false)
+    assert.equal(result.failure_code, 'READINESS_TIMEOUT')
+    assert.equal(result.device_readiness.input_ready, false)
+    const lockedPredicate = await call('wait_for_ui', { selector: { text: 'Ready' }, requireReady: true, timeout_ms: 300, poll_interval_ms: 100 })
+    assert.equal(lockedPredicate.status, 'timeout')
+    assert.equal(lockedPredicate.device_readiness.lock_state, 'locked')
+    deviceState = 'unlocked'; reads = 0
+    result = await call('wait_for_app_ready', { stabilityMs: 100, timeoutMs: 1500, pollIntervalMs: 100 })
+    assert.equal(result.success, true, 'fresh unlocked evidence permits recovery')
+    assert.equal(result.device_readiness.input_ready, null, 'stable UI and unlocked flags do not prove input readiness')
+    deviceState = 'unknown'
     mode = 'loading'; reads = 0
     result = await call('get_app_readiness')
     assert.equal(result.readiness.state, 'loading')

package/test/unit/server/run_journey.test.ts

@@ -42,7 +42,7 @@ async function run() {
     assert.strictEqual(result.steps[1].status, 'failed')
     assert.deepStrictEqual(result.steps[2], {
       id: 'not-run', type: 'wait', status: 'not_run', success: false,
-      reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 }
+      reason: 'PREVIOUS_STEP_FAILED', result: null
     })
 
     let postActionReads = 0
@@ -62,6 +62,7 @@ async function run() {
     })
     const light = JSON.parse(lightResponse.content[0].text)
     assert.strictEqual(light.success, true)
+    assert.ok(light.steps[0].result.device_readiness, 'journey action retains device evidence in compact mode')
     assert.deepStrictEqual(Object.keys(light.timing), ['total_ms'])
     assert.deepStrictEqual(light.steps[0].result.verification, { mode: 'light', status: 'observed' })
     assert.strictEqual(light.steps[0].result.verification_diagnostic, undefined)

package/test/unit/server/selector_tap_target.test.ts

@@ -43,7 +43,8 @@ async function run() {
     error = 'Failed to get UI tree: ACTION_TIMEOUT'
     const timeout = await call()
     assert.equal(timeout.failure_code, 'ACTION_TIMEOUT', 'Observation timeout must not claim that the label is missing')
-    assert.equal(timeout.evidence.dispatch_started_at_ms, null)
+    const retained = JSON.parse((await handleToolCall('get_interaction_diagnostics', { sessionId: timeout.diagnostics.session_id, resultId: timeout.diagnostics.result_id })).content[0].text!)
+    assert.equal(retained.result.evidence.dispatch_started_at_ms, null)
     assert.equal(taps.length, tapCount)
     error = undefined
 

package/test/unit/server/system-trace.test.ts

@@ -8,6 +8,7 @@ import { withEvidence, bindSystemTrace, bindEvidenceDevice } from '../../../src/
 const parse = (r: any) => JSON.parse(r.content[0].text)
 async function run() {
   const originalLink = systemTraces.link, originalStart = systemTraces.start, originalControl = systemTraces.control
+  const originalCapabilities = systemTraces.iosCapabilities
   const originalApp = AndroidManage.prototype.startApp
   const id = '62a51510-c303-4a1b-af0e-f97cc976d740'
   let dispatched = 0, starts = 0
@@ -24,8 +25,16 @@ async function run() {
     }
     systemTraces.start = async () => { starts++; throw new Error('must not run') }
     const ios = await handleToolCall('start_system_trace', { platform: 'ios' })
-    assert.equal(parse(ios).error.code, 'UNSUPPORTED_PLATFORM'); assert.equal(starts, 0)
-    assert.equal(parse(await handleToolCall('get_system_trace_capabilities', { platform: 'ios' })).supported, false)
+    assert.equal(parse(ios).error.code, 'INVALID_ARGUMENT'); assert.equal(starts, 0)
+    assert.equal(parse(await handleToolCall('get_system_trace_capabilities', { platform: 'ios' })).error.code, 'INVALID_ARGUMENT')
+    for (const args of [{platform:'ios',deviceId:'sim'}, {platform:'android',appId:'fixture'}, {platform:'android',template:'Time Profiler'}, {platform:'ios',deviceId:'sim',appId:'fixture',template:'Other'}, {platform:'ios',deviceId:'sim',appId:'invalid bundle'}]) {
+      assert.equal(parse(await handleToolCall('start_system_trace', args)).error.code, 'INVALID_ARGUMENT')
+    }
+    systemTraces.iosCapabilities = async (deviceId, appId, template) => {
+      assert.equal(deviceId, 'sim'); assert.equal(appId, 'fixture'); assert.equal(template, 'Time Profiler')
+      return {supported: false, backend:'xctrace'} as any
+    }
+    assert.equal(parse(await handleToolCall('get_system_trace_capabilities', {platform:'ios',deviceId:'sim',appId:'fixture',template:'Time Profiler'})).backend, 'xctrace')
     for (const name of ['stop_system_trace', 'cancel_system_trace', 'get_system_trace_status']) {
       assert.equal(parse(await handleToolCall(name, { traceId: id, deviceId: 'wrong' })).error.code, 'INVALID_ARGUMENT')
       assert.equal(parse(await handleToolCall(name, { traceId: id })).error.code, 'TRACE_NOT_FOUND')
@@ -41,14 +50,16 @@ async function run() {
     }
     const result = parse(await handleToolCall('run_journey', journey))
     assert.equal(result.success, true, JSON.stringify(result)); assert.equal(dispatched, 1)
-    assert.equal(result.evidence.trace_context.trace_id, id)
-    assert.equal(result.evidence.trace_context.supported, true)
+    assert.equal(result.evidence.trace_id, id)
+    const retained = parse(await handleToolCall('get_interaction_diagnostics', { sessionId: result.diagnostics.session_id, resultId: result.diagnostics.result_id }))
+    assert.equal(retained.result.evidence.trace_context.supported, true)
     assert.equal(result.evidence.correlation_id, correlation)
-    assert.equal(result.steps[0].result.evidence.trace_context.trace_id, id)
+    assert.equal(result.steps[0].result.evidence.trace_id, id)
     assert.equal(result.steps[0].result.evidence.correlation_id, correlation)
     assert.equal(result.system_trace.coverage, 'covered')
     const plain = parse(await handleToolCall('run_journey', { ...journey, systemTraceId: undefined }))
-    assert.deepEqual(plain.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
+    const retainedPlain = parse(await handleToolCall('get_interaction_diagnostics', { sessionId: plain.diagnostics.session_id, resultId: plain.diagnostics.result_id }))
+    assert.deepEqual(retainedPlain.result.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
     const [linked, independent] = await Promise.all([
       withEvidence({ journey: true }, async () => { bindSystemTrace(id); bindEvidenceDevice({ platform: 'android', id: 'trace-device' }); return withEvidence({ action: true }, async () => {}) }),
       withEvidence({ journey: true }, async () => {})
@@ -57,7 +68,7 @@ async function run() {
     assert.equal(independent.evidence.trace_context.trace_id, null)
     console.log('system trace tool contracts and journey evidence: PASS')
   } finally {
-    systemTraces.link = originalLink; systemTraces.start = originalStart; systemTraces.control = originalControl
+    systemTraces.iosCapabilities = originalCapabilities; systemTraces.link = originalLink; systemTraces.start = originalStart; systemTraces.control = originalControl
     AndroidManage.prototype.startApp = originalApp; _resetDeviceListersForTests()
   }
 }

package/test/unit/utils/app-installation.test.ts

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { probeInstallation, installationFields } from '../../../src/utils/app-installation.js'
+import { listAndroidDevices } from '../../../src/utils/android/utils.js'
+import { checkAndroid } from '../../../src/system/android.js'
+import { ToolsManage } from '../../../src/manage/index.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+const dir = await mkdtemp(path.join(os.tmpdir(), 'installation-test-'))
+const binary = path.join(dir, 'adb')
+const saved = { ...process.env }
+try {
+  await writeFile(binary, `#!/usr/bin/env node
+const args = process.argv.slice(2)
+if (args[0] === '--version') console.log('Android Debug Bridge version 1.0.41')
+else if (args[0] === 'devices') console.log(process.env.ONE_INSTALL_DEVICE ? 'List of devices attached\\na device' : 'List of devices attached\\na device\\nb device')
+else if (args.includes('getprop')) console.log('14')
+else if (args.includes('logcat')) console.log('log')
+else if (args.includes('listapps')) {
+  if (args.at(-1) === 'failed') process.exit(1)
+  if (args.at(-1) === 'malformed') {console.log('not a plist'); process.exit(0)}
+  console.log('<?xml version="1.0"?><plist version="1.0"><dict><key>com.example.app</key><dict/></dict></plist>')
+}
+else {
+  const id = args[1], app = args.at(-1)
+  if (id === 'b' && args.includes('path')) process.exit(1)
+  if (id === 'failed') process.exit(1)
+  if (id === 'malformed') console.log('Error: query failed')
+  else if (id === 'slow') setTimeout(() => console.log('package:/late.apk'), 1000)
+  else if (app === 'com.example.app' && id !== 'b') console.log('package:/data/app/base.apk')
+}
+`, { mode: 0o755 })
+  process.env.ADB_PATH = binary
+  delete process.env.MCP_TARGET_PACKAGE
+  delete process.env.MCP_TARGET_APP_ID
+  const check = (id: string, app: string | undefined = 'com.example.app') => probeInstallation(binary, id, app, 'android-current-user')
+  assert.equal((await check('a')).status, 'installed')
+  assert.equal((await check('b')).status, 'absent')
+  for (const id of ['failed', 'malformed']) {
+    const result = await check(id)
+    assert.equal(result.status, 'unknown')
+    assert(!JSON.stringify(installationFields(result)).includes('appInstalled'))
+  }
+  assert.equal((await probeInstallation(binary, 'a', undefined, 'android-current-user')).reason, 'APP_ID_NOT_PROVIDED')
+  assert.equal((await check('a', 'bad;input')).checkedAt, null)
+  assert.equal((await probeInstallation(binary, 'a', 'com.example.app', 'android-current-user', false)).reason, 'DEVICE_UNAVAILABLE')
+  assert.equal((await runWithBudget(50, () => check('slow'))).status, 'unknown')
+  if (process.platform === 'darwin') {
+    assert.equal((await probeInstallation(binary, 'a', 'com.example.app', 'ios-simulator')).status, 'installed')
+    assert.equal((await probeInstallation(binary, 'a', 'com.missing.app', 'ios-simulator')).status, 'absent')
+    assert.equal((await probeInstallation(binary, 'failed', 'com.example.app', 'ios-simulator')).status, 'unknown')
+    assert.equal((await probeInstallation(binary, 'malformed', 'com.example.app', 'ios-simulator')).status, 'unknown')
+  }
+  const inventory = await listAndroidDevices()
+  assert.equal(inventory.length, 2)
+  assert(inventory.every(device => device.appInstallation?.reason === 'APP_ID_NOT_PROVIDED' && !Object.hasOwn(device, 'appInstalled')))
+  const scoped = await listAndroidDevices('com.example.app')
+  assert.deepEqual(scoped.map(device => device.appInstalled), [true, false])
+  assert.deepEqual(scoped.map(device => device.appInstallation?.deviceId), ['a', 'b'])
+  process.env.MCP_TARGET_PACKAGE = 'com.example.app'
+  const system = await checkAndroid()
+  assert.equal(system.appInstalled, undefined)
+  assert.deepEqual(system.appInstallations.map(result => result.status), ['installed', 'absent'])
+  assert(system.issues.some(issue => issue.includes('device b')))
+  process.env.ONE_INSTALL_DEVICE = '1'
+  assert.equal((await checkAndroid()).appInstalled, true)
+  process.env.MCP_TARGET_PACKAGE = 'bad;input'
+  const invalid = await checkAndroid()
+  assert.equal(invalid.appInstalled, undefined)
+  assert.equal(invalid.appInstallations[0].checkedAt, null)
+  await assert.rejects(() => ToolsManage.listDevicesHandler({ appId: 'bad;input' }), /Invalid appId/)
+  console.log('app installation tests passed')
+} finally {
+  process.env = saved
+  await rm(dir, { recursive: true, force: true })
+}

package/test/unit/utils/benchmark-metrics.test.ts

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+
+const program = `
+import assert from 'node:assert/strict';
+import { withBenchmarkRequest, benchmarkStage } from './src/utils/benchmark-metrics.ts';
+import { measure, withTiming } from './src/utils/timing.ts';
+const values = {};
+const result = await withBenchmarkRequest('outer', () => withTiming(values, async () => {
+  await measure('dispatch_ms', () => benchmarkStage('subprocess_ms', async () => 1));
+  return { unchanged: true };
+}));
+assert.deepEqual(result, { unchanged: true });
+assert.ok(values.dispatch_ms >= 0);
+await Promise.all(['first', 'second'].map(tool => withBenchmarkRequest(tool, () => benchmarkStage(tool, async () => tool))));
+try { await withBenchmarkRequest('failure', async () => { throw Error('secret'); }); } catch {}
+`
+for (const enabled of ['0', '1']) {
+  const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', program], {
+    cwd: process.cwd(), encoding: 'utf8', timeout: 15000,
+    env: { ...process.env, MOBILE_DEBUG_MCP_LATENCY_METRICS: enabled }
+  })
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout, '')
+  if (enabled === '0') assert.equal(result.stderr, '')
+  else {
+    const events = result.stderr.trim().split('\n').map(line => JSON.parse(line))
+    assert.equal(events.length, 4)
+    assert.equal(new Set(events.map(event => event.request_id)).size, 4)
+    assert.deepEqual(events.find(event => event.tool === 'outer').spans.map((span: { stage: string }) => span.stage), ['subprocess_ms', 'dispatch_ms'])
+    for (const tool of ['first', 'second']) assert.deepEqual(events.find(event => event.tool === tool).spans.map((span: { stage: string }) => span.stage), [tool])
+    assert.equal(events.find(event => event.tool === 'failure').handler_completed, false)
+    assert.ok(!result.stderr.includes('secret'))
+  }
+}
+console.log('Opt-in latency metrics, failure and request isolation: PASS')

package/test/unit/utils/resolve_device.test.ts

@@ -51,6 +51,17 @@ async function run() {
       }
     )
 
+    const base = { platform: 'android', model: 'Fixture', simulator: true }
+    _setDeviceListersForTests({ listAndroidDevices: async () => [
+      { ...base, id: 'unknown', osVersion: '17', appInstalled: true, appInstallation: {
+        status: 'unknown', appId: 'com.example.app', deviceId: 'unknown', scope: 'android-current-user', checkedAt: null, reason: 'CHECK_FAILED'
+      } },
+      { ...base, id: 'installed', osVersion: '16', appInstallation: {
+        status: 'installed', appId: 'com.example.app', deviceId: 'installed', scope: 'android-current-user', checkedAt: new Date(0).toISOString()
+      } }
+    ] })
+    assert.equal((await resolveTargetDevice({ platform: 'android', appId: 'com.example.app' })).id, 'installed')
+    assert.equal((await resolveTargetDevice({ platform: 'android', appId: 'com.other.app' })).id, 'unknown')
     console.log('resolve-device tests passed')
   } finally {
     _resetDeviceListersForTests()