mobile-debug-mcp 0.31.0 → 0.32.1

package/test/unit/server/interaction_modes.test.ts

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { AndroidManage } from '../../../src/manage/android.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  const treeOriginal = ToolsObserve.getUITreeHandler
+  const fingerprintOriginal = ToolsObserve.getScreenFingerprintHandler
+  const tapOriginal = ToolsInteract.tapHandler
+  const launchOriginal = AndroidManage.prototype.startApp
+  const device: any = { platform: 'android', id: 'fixture' }
+  let dispatched = false
+  let postReads = 0
+  let fingerprints = 0
+  ToolsObserve.getUITreeHandler = async () => {
+    if (dispatched) postReads++
+    return { device, elements: [{ text: 'Go', stable_id: 'go', bounds: [0, 0, 40, 40], visible: true, enabled: true, clickable: true }] } as any
+  }
+  ToolsObserve.getScreenFingerprintHandler = async () => { fingerprints++; return { fingerprint: 'fixture' } as any }
+  ToolsInteract.tapHandler = async () => { dispatched = true; return { success: true, device } as any }
+  AndroidManage.prototype.startApp = async () => { dispatched = true; return { appStarted: true, device } as any }
+  try {
+    for (const tool of ['tap_element', 'start_app']) {
+      for (const mode of ['none', 'light', 'full']) {
+        dispatched = false; postReads = 0; fingerprints = 0
+        const response = await handleToolCall(tool, { platform: 'android', deviceId: 'fixture', ...(tool === 'tap_element' ? { selector: { text: 'Go' } } : { appId: 'fixture' }), verificationMode: mode, responseMode: 'compact' })
+        const result = JSON.parse(response.content[0].text!)
+        assert.equal(result.success, true, JSON.stringify(result))
+        assert.equal(postReads, mode === 'light' ? 1 : 0)
+        assert.equal(fingerprints, mode === 'full' ? 2 : 0)
+        assert.equal(result.device, undefined)
+        assert.equal(result.trace, undefined)
+        assert.equal(result.dispatch_started, true)
+        assert.deepEqual(Object.keys(result.timing), ['total_ms'])
+        if (mode !== 'full') assert.equal(result.lifecycle_state, 'pending_verification')
+      }
+    }
+    ToolsObserve.getUITreeHandler = async () => { throw new Error('offline') }
+    const result = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture', verificationMode: 'light', responseMode: 'compact' })).content[0].text!)
+    assert.equal(result.success, true)
+    assert.equal(result.verification.status, 'unavailable')
+    assert.equal(result.verification_diagnostic.retryable, true)
+    ToolsInteract.tapHandler = async () => { markDispatchStarted(); dispatched = true; return { success: false, error: 'ACTION_TIMEOUT', device } as any }
+    const timedOut = JSON.parse((await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1, verificationMode: 'none', responseMode: 'compact' })).content[0].text!)
+    assert.equal(timedOut.failure_code, 'ACTION_TIMEOUT')
+    assert.equal(timedOut.delivery_status, 'unknown')
+    assert.equal(timedOut.retryable, false)
+    AndroidManage.prototype.startApp = async () => ({ appStarted: false, device, error: 'launch failed', diagnostics: { runResult: { exitCode: 1, stdout: '', stderr: 'launch failed' } } } as any)
+    const failedLaunch = JSON.parse((await handleToolCall('start_app', { platform: 'android', appId: 'fixture' })).content[0].text!)
+    assert.equal(failedLaunch.details.diagnostics.runResult.exitCode, 1)
+  } finally {
+    ToolsObserve.getUITreeHandler = treeOriginal
+    ToolsObserve.getScreenFingerprintHandler = fingerprintOriginal
+    ToolsInteract.tapHandler = tapOriginal
+    AndroidManage.prototype.startApp = launchOriginal
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/server/operation_budget.test.ts

@@ -0,0 +1,45 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { runWithBudget, remainingBudget, markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { execCmd } from '../../../src/utils/exec.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  const markerDir = mkdtempSync(path.join(tmpdir(), 'mcp-exec-close-'))
+  try {
+    const marker = path.join(markerDir, 'closed')
+    const command = `process.on('SIGTERM', () => setTimeout(() => { require('fs').writeFileSync(${JSON.stringify(marker)}, 'closed'); process.exit(0) }, 50)); setInterval(() => {}, 1000)`
+    const response = await execCmd(process.execPath, ['-e', command], { timeout: 250 })
+    assert.equal(response.stderr, 'ACTION_TIMEOUT')
+    assert.equal(existsSync(marker), true, 'timeout must await child close before returning')
+  } finally {
+    rmSync(markerDir, { recursive: true, force: true })
+  }
+  await runWithBudget(100, async budget => {
+    assert.equal(budget.dispatchStarted, false)
+    markDispatchStarted()
+    assert.equal(budget.dispatchStarted, true)
+    const response = await execCmd(process.execPath, ['-e', 'setTimeout(() => {}, 10000)'])
+    assert.equal(response.stderr, 'ACTION_TIMEOUT')
+    assert.throws(() => remainingBudget(), /ACTION_TIMEOUT/)
+  })
+  await runWithBudget(1, async budget => {
+    await new Promise(resolve => setTimeout(resolve, 5))
+    assert.throws(() => markDispatchStarted(), /ACTION_TIMEOUT/)
+    assert.equal(budget.dispatchStarted, false)
+  })
+  const originalTree = ToolsObserve.getUITreeHandler
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('transient observation error') }
+  try {
+    await assert.rejects(
+      () => runWithBudget(30, () => ToolsInteract.waitForUIHandler({ selector: { text: 'missing' }, timeout_ms: 1000, poll_interval_ms: 5, platform: 'android', deviceId: 'fixture' })),
+      /ACTION_TIMEOUT/
+    )
+  } finally {
+    ToolsObserve.getUITreeHandler = originalTree
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -37,7 +37,7 @@ async function run() {
 
     const missingBuildResponse = await handleToolCall('build_app', { projectPath: '/tmp/project' })
     const missingBuildPayload = JSON.parse((missingBuildResponse as any).content[0].text)
-    assert.deepStrictEqual(missingBuildPayload, {
+    assert.deepStrictEqual({ error: missingBuildPayload.error }, {
       error: {
         tool: 'build_app',
         message: 'Missing or invalid string argument: platform'
@@ -236,7 +236,7 @@ async function run() {
     const failingTapResponse = await handleToolCall('tap', { platform: 'android', x: 1, y: 2 })
     assert.strictEqual((failingTapResponse as any).content.length, 1)
     const failingTapPayload = JSON.parse((failingTapResponse as any).content[0].text)
-    assert.deepStrictEqual(failingTapPayload, {
+    assert.deepStrictEqual({ error: failingTapPayload.error }, {
       error: {
         tool: 'tap',
         message: 'boom'
@@ -255,7 +255,7 @@ async function run() {
 
     const missingArgResponse = await handleToolCall('tap', { platform: 'android', x: 1 })
     const missingArgPayload = JSON.parse((missingArgResponse as any).content[0].text)
-    assert.deepStrictEqual(missingArgPayload, {
+    assert.deepStrictEqual({ error: missingArgPayload.error }, {
       error: {
         tool: 'tap',
         message: 'Missing or invalid number argument: y'

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

@@ -0,0 +1,120 @@
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import assert from 'assert'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  const originalWait = (ToolsInteract as any).waitForUIHandler
+  const originalExpectVisible = (ToolsInteract as any).expectElementVisibleHandler
+  const originalTap = (ToolsInteract as any).tapElementHandler
+  const originalTree = (ToolsObserve as any).getUITreeHandler
+  let resolutions = 0
+  _setDeviceListersForTests({ listAndroidDevices: async () => { resolutions++; return [{ id: 'fixture', platform: 'android' } as any] } })
+  try {
+    const calls: string[] = []
+    ;(ToolsInteract as any).waitForUIHandler = async () => {
+      calls.push('wait')
+      return { status: 'success', element: { elementId: 'ready' } }
+    }
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => {
+      calls.push('assert')
+      return { success: false, failure_code: 'TIMEOUT' }
+    }
+
+    const response: any = await handleToolCall('run_journey', {
+      platform: 'android',
+      steps: [
+        { id: 'wait-ready', type: 'wait', selector: { text: 'Ready' } },
+        { id: 'assert-ready', type: 'assert', assertion: { kind: 'element_visible', selector: { text: 'Ready' } } },
+        { id: 'not-run', type: 'wait', selector: { text: 'Later' } }
+      ]
+    })
+    const result = JSON.parse(response.content[0].text)
+    assert.strictEqual(resolutions, 1)
+    assert.deepStrictEqual(calls, ['wait', 'assert'])
+    await handleToolCall('run_journey', { platform: 'android', steps: [{ id: 'valid', type: 'wait', selector: { text: 'Ready' } }, { id: 'bad', type: 'tap' }] })
+    assert.strictEqual(resolutions, 1, 'Invalid later steps must fail before device work')
+    assert.deepStrictEqual(calls, ['wait', 'assert'])
+    assert.strictEqual(result.success, false)
+    assert.strictEqual(result.stopped_at_step_id, 'assert-ready')
+    assert.strictEqual(result.steps[0].status, 'passed')
+    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 }
+    })
+
+    let postActionReads = 0
+    ;(ToolsObserve as any).getUITreeHandler = async () => { postActionReads++; throw new Error('Unexpected duplicate observation') }
+    ;(ToolsInteract as any).waitForUIHandler = async () => ({ status: 'success', element: { elementId: 'target' }, _tree: {} })
+    ;(ToolsInteract as any).tapElementHandler = async (args: any) => {
+      assert.strictEqual(args.verificationMode, 'none')
+      return { success: true, action_id: 'tap', action_type: 'tap_element' }
+    }
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({ success: true, observed: { matched_count: 1 } })
+    const lightResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const light = JSON.parse(lightResponse.content[0].text)
+    assert.strictEqual(light.success, true)
+    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)
+    assert.strictEqual(postActionReads, 0, 'The following assertion supplies the fresh observation')
+    ;(ToolsInteract as any).expectElementVisibleHandler = async () => ({ success: false, failure_code: 'TIMEOUT', observed: { matched_count: 0 } })
+    const failedAssertionResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const failedAssertion = JSON.parse(failedAssertionResponse.content[0].text)
+    assert.strictEqual(failedAssertion.success, false)
+    assert.deepStrictEqual(failedAssertion.steps[0].result.verification, { mode: 'light', status: 'observed' })
+    assert.strictEqual(postActionReads, 0)
+
+    ;(ToolsInteract as any).waitForUIHandler = originalWait
+    ;(ToolsInteract as any).expectElementVisibleHandler = originalExpectVisible
+    let dispatchedAt = 0
+    const readTimes: number[] = []
+    ;(ToolsObserve as any).getUITreeHandler = async () => {
+      readTimes.push(performance.now())
+      const target = readTimes.length === 1
+      return {
+        device: { platform: 'android', id: 'fixture' },
+        captured_at_ms: Date.now(),
+        elements: [{ contentDescription: target ? 'target' : 'result', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true }]
+      }
+    }
+    ;(ToolsInteract as any).tapElementHandler = async () => {
+      dispatchedAt = performance.now()
+      return { success: true, action_id: 'tap', action_type: 'tap_element' }
+    }
+    const freshResponse: any = await handleToolCall('run_journey', {
+      platform: 'android', responseMode: 'compact', defaults: { verificationMode: 'light' },
+      steps: [
+        { id: 'tap-target', type: 'tap', selector: { accessibility_id: 'target' } },
+        { id: 'assert-result', type: 'assert', assertion: { kind: 'element_visible', selector: { accessibility_id: 'result' } } }
+      ]
+    })
+    const fresh = JSON.parse(freshResponse.content[0].text)
+    assert.strictEqual(fresh.success, true)
+    assert.strictEqual(readTimes.length, 3, 'target selection and two stability samples require separate reads')
+    assert.ok(readTimes[0] < dispatchedAt)
+    assert.ok(readTimes[1] >= dispatchedAt && readTimes[2] >= dispatchedAt, 'assertion reads must follow dispatch')
+  } finally {
+    _resetDeviceListersForTests()
+    ;(ToolsInteract as any).waitForUIHandler = originalWait
+    ;(ToolsInteract as any).expectElementVisibleHandler = originalExpectVisible
+    ;(ToolsInteract as any).tapElementHandler = originalTap
+    ;(ToolsObserve as any).getUITreeHandler = originalTree
+  }
+}
+
+run().catch((error) => { console.error(error); process.exit(1) })

package/test/unit/server/tap_selector.test.ts

@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+
+async function run() {
+  const originalWait = ToolsInteract.waitForUIHandler
+  const originalTap = ToolsInteract.tapElementHandler
+  let tapCount = 0
+  let lastWait: any
+  let resolution: any
+  ToolsInteract.waitForUIHandler = async (args: any) => { lastWait = args; return resolution }
+  ToolsInteract.tapElementHandler = async (args: any) => {
+    tapCount++
+    assert.equal(args.elementId, 'selected')
+    assert.deepEqual(args.freshTree, { elements: [] })
+    return { action_id: 'tap', action_type: 'tap_element', success: true, lifecycle_state: 'pending_verification' } as any
+  }
+  try {
+    const selector = { accessibility_id: 'save' }
+    resolution = { status: 'success', element: { elementId: 'selected' }, _tree: { elements: [] } }
+    const success = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(success.success, true)
+    assert.equal(tapCount, 1)
+    assert.equal(lastWait.condition, 'clickable')
+    assert.equal(lastWait.singleObservation, true)
+    assert.equal(lastWait.singleAttempt, true)
+    assert.equal(lastWait.rejectAmbiguous, true)
+
+    await handleToolCall('tap_element', {
+      selector, waitFor: { condition: 'visible', timeoutMs: 700, pollIntervalMs: 80 },
+      platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })
+    assert.equal(lastWait.condition, 'visible')
+    assert.equal(lastWait.timeout_ms, 700)
+    assert.equal(lastWait.poll_interval_ms, 80)
+    assert.equal(lastWait.singleAttempt, false)
+    assert.equal(lastWait.rejectAmbiguous, false)
+    assert.equal(tapCount, 2)
+
+    resolution = { status: 'timeout', error: { code: 'AMBIGUOUS_TARGET' } }
+    const ambiguous = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(ambiguous.failure_code, 'AMBIGUOUS_TARGET')
+    assert.equal(tapCount, 2)
+
+    resolution = { status: 'timeout', error: { code: 'ELEMENT_NOT_FOUND' } }
+    const missing = JSON.parse((await handleToolCall('tap_element', {
+      selector, platform: 'android', verificationMode: 'none', responseMode: 'compact'
+    })).content[0].text!)
+    assert.equal(missing.failure_code, 'ELEMENT_NOT_FOUND')
+    assert.equal(missing.dispatch_started, false)
+    assert.equal(missing.retryable, true)
+    assert.equal(tapCount, 2)
+
+    const invalid = await handleToolCall('tap_element', {
+      elementId: 'old', selector, waitFor: {}, platform: 'android'
+    })
+    assert.match(JSON.parse(invalid.content[0].text!).error.message, /Invalid input/)
+    assert.equal(tapCount, 2)
+  } finally {
+    ToolsInteract.waitForUIHandler = originalWait
+    ToolsInteract.tapElementHandler = originalTap
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })