mobile-debug-mcp 0.32.4 → 0.34.0

package/test/device/automated/observe/system-trace.smoke.ts

@@ -0,0 +1,104 @@
+import { execCmd } from '../../../../src/utils/exec.js'
+import { getAdbCmd } from '../../../../src/utils/android/utils.js'
+import { createHash } from 'node:crypto'
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { inspectPerfetto } from '../../../helpers/perfetto.js'
+
+async function run() {
+  if (process.env.SKIP_DEVICE_TESTS === '1') { console.log('System trace smoke: SKIPPED (SKIP_DEVICE_TESTS=1)'); return }
+  const client = new Client({ name: 'system-trace-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const parse = (r: any) => JSON.parse(r.content[0].text)
+  const call = async (name: string, args: Record<string, unknown>) => parse(await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 }))
+  const owned: string[] = [], artifacts: string[] = []
+  try {
+    await client.connect(transport)
+    const devices = await call('list_devices', {})
+    const device = devices.devices.find((d: any) => d.platform === 'android' && d.simulator)
+    assert.ok(device, 'A running Android emulator is required')
+    const target = { platform: 'android', deviceId: device.id }
+    const cap = await call('get_system_trace_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    const fixtureLaunch = await call('start_app', { ...target, appId: 'com.android.settings', verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(fixtureLaunch.success, true)
+    const baseline = await call('get_ui_tree', { ...target, responseMode: 'debug' })
+    const settingsNode = baseline.elements?.find((e: any) => e.visible && e.resourceId?.startsWith('com.android.settings:id/'))
+    assert.ok(settingsNode, 'Fresh baseline must contain a visible Settings-owned UI resource')
+    const settingsSelector = { resource_id: settingsNode.resourceId }
+    const start = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(start.trace_id)
+    assert.equal(start.state, 'recording', JSON.stringify(start))
+    const journey = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [
+        { id: 'settings', type: 'start_app', appId: 'com.android.settings', verificationMode: 'none' },
+        { id: 'settings-visible', type: 'assert', timeoutMs: 10000, assertion: { kind: 'element_visible', selector: settingsSelector } }
+      ] })
+    assert.equal(journey.success, true, JSON.stringify(journey))
+    assert.equal(journey.steps[1].status, 'passed', 'The baseline Settings-owned UI element must remain semantically visible')
+    assert.equal(journey.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.steps[0].result.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.system_trace.coverage, 'covered')
+    const stop = await call('stop_system_trace', { traceId: start.trace_id })
+    if (stop.artifact) artifacts.push(stop.artifact.path)
+    assert.equal(stop.state, 'completed', JSON.stringify(stop)); assert.equal(stop.cleanup.status, 'complete')
+    assert.deepEqual(stop.correlation_ids, [journey.evidence.correlation_id])
+    const content = inspectPerfetto(await fs.readFile(stop.artifact.path), 30000)
+    assert.equal((await call('stop_system_trace', { traceId: start.trace_id })).artifact.path, stop.artifact.path)
+    const rejected = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [{ id: 'must-not-launch', type: 'start_app', appId: 'com.invalid.trace.smoke' }] })
+    assert.equal(rejected.error.code, 'TRACE_NOT_FOUND')
+    const cancel = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(cancel.trace_id)
+    const cancelled = await call('cancel_system_trace', { traceId: cancel.trace_id })
+    assert.equal(cancelled.state, 'cancelled', JSON.stringify(cancelled))
+    assert.equal((await call('get_system_trace_status', { traceId: cancel.trace_id })).artifact, null)
+    const short = await call('start_system_trace', { ...target, durationMs: 1001 })
+    owned.push(short.trace_id)
+    assert.equal(short.state, 'recording', JSON.stringify(short))
+    let ended = short
+    for (let i = 0; i < 30 && ended.state === 'recording'; i++) {
+      await new Promise(resolve => setTimeout(resolve, 200))
+      ended = await call('get_system_trace_status', { traceId: short.trace_id })
+    }
+    if (ended.artifact) artifacts.push(ended.artifact.path)
+    assert.equal(ended.state, 'completed', JSON.stringify(ended)); assert.equal(ended.completion_reason, 'duration_limit')
+    const durationContent = inspectPerfetto(await fs.readFile(ended.artifact.path), 1001)
+    const shutdownClient = new Client({ name: 'system-trace-shutdown-smoke', version: '1.0.0' })
+    const shutdownTransport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+    let shutdownTrace: any
+    let shutdownDiagnostics = ''
+    try {
+      await shutdownClient.connect(shutdownTransport)
+      shutdownTransport.stderr?.on('data', data => { shutdownDiagnostics += String(data) })
+      shutdownTrace = parse(await shutdownClient.callTool({ name: 'start_system_trace', arguments: { ...target, durationMs: 30000 } }, undefined, { timeout: 120000 }))
+      assert.equal(shutdownTrace.state, 'recording')
+    } finally { await shutdownClient.close() }
+    const remote = shutdownTrace.cleanup.remaining_resources.find((r: string) => r.startsWith('/data/misc/perfetto-traces/mcp-'))
+    assert.ok(remote)
+    const absent = await execCmd(getAdbCmd(), ['-s', device.id, 'shell', 'test', '!', '-e', remote], { timeout: 10000 })
+    assert.equal(absent.exitCode, 0, `Shutdown must stop and remove its owned device capture: ${shutdownTrace.trace_id}; ${shutdownDiagnostics}; ${absent.stderr}`)
+    const buildHash = createHash('sha256')
+    for (const file of ['dist/server.js', 'dist/observe/system-trace.js', 'dist/observe/system-trace-android.js', 'dist/server/tool-handlers.js', 'dist/observe/evidence.js']) buildHash.update(await fs.readFile(file))
+    const report = { status: 'PASS', build_sha256: buildHash.digest('hex'), runtime: process.version, server: client.getServerVersion(), device: device.id, osVersion: device.osVersion,
+      starting_state: 'System Settings fixture', journey: 'start Settings, assert baseline Settings-owned resource visible in UI tree; explicit trace association',
+      trace_id: start.trace_id, correlation_id: journey.evidence.correlation_id, phases: {
+        capture_started_at_ms: stop.capture_started_at_ms, capture_completed_at_ms: stop.capture_completed_at_ms },
+      artifact_bytes: stop.artifact.size_bytes, content, durationContent, cancel: 'PASS', expired_journey: 'PASS', active_shutdown: 'PASS',
+      cleanup: 'Device capture files removed; test host artifacts removed in finally. No settings or app data changed. Settings remains foreground.' }
+    console.log(JSON.stringify(report))
+    if (process.env.SYSTEM_TRACE_EVIDENCE_PATH) await fs.writeFile(process.env.SYSTEM_TRACE_EVIDENCE_PATH, JSON.stringify(report, null, 2) + '\n')
+  } finally {
+    const cleanupErrors: string[] = []
+    for (const traceId of owned) {
+      try { const r = await call('cancel_system_trace', { traceId }); if (r.artifact && !artifacts.includes(r.artifact.path)) artifacts.push(r.artifact.path); if (r.cleanup?.status !== 'complete') cleanupErrors.push(traceId) } catch { cleanupErrors.push(traceId) }
+    }
+    await client.close()
+    for (const file of artifacts) await fs.rm(path.dirname(file), { recursive: true, force: true })
+    assert.deepEqual(cleanupErrors, [], 'Owned trace cleanup failed')
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/conditional_actions.manual.ts

@@ -0,0 +1,95 @@
+// Run against a built checkout and an explicitly selected simulator in system Settings.
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { writeFile } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+function arg(name: string) { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined }
+async function run() {
+  const platform = arg('--platform')
+  const deviceId = arg('--id')
+  const targetText = arg('--target-text')
+  const destinationText = arg('--destination-text')
+  const output = arg('--output')
+  assert.ok(platform === 'android' || platform === 'ios', '--platform android|ios is required')
+  assert.ok(deviceId && targetText && destinationText && output, '--id, --target-text, --destination-text and --output are required')
+  const repository = fileURLToPath(new URL('../../../../', import.meta.url))
+  const transport = new StdioClientTransport({ command: process.execPath, args: [path.join(repository, 'dist/server.js')], cwd: repository, stderr: 'pipe' })
+  const client = new Client({ name: 'conditional-device-verification', version: '1.0.0' })
+  const evidence: any = { platform, deviceId, checked_at: new Date().toISOString(), source: 'built dist/server.js over MCP stdio', scenarios: [] }
+  transport.stderr?.on('data', chunk => process.stderr.write(chunk))
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const result = await client.callTool({ name, arguments: { platform, deviceId, ...args } }, undefined, { timeout: 120000 })
+    const item: any = result.content.find((item: any) => item.type === 'text')
+    return JSON.parse(item.text)
+  }
+  const observe = async () => {
+    const result = await call('get_ui_tree', {})
+    assert.equal(result.error, undefined, JSON.stringify(result))
+    assert.ok(result.resolution.width > 0 && result.elements.length > 0, 'nonempty usable hierarchy required')
+    return result
+  }
+  const contains = (tree: any, text: string) => tree.elements.some((element: any) => element.text === text || element.contentDescription === text || element.resourceId === text)
+  try {
+    await client.connect(transport)
+    evidence.server = client.getServerVersion()
+    const tools = await client.listTools()
+    assert.ok((tools.tools.find(tool => tool.name === 'tap')?.inputSchema.properties as any)?.expectedState, 'newly built server advertises the condition')
+    const baseline = await observe()
+    assert.ok(contains(baseline, targetText), `starting screen must contain ${targetText}`)
+    assert.ok(!contains(baseline, destinationText), 'destination must not already be present on the starting screen')
+    const expectedState = { snapshotSessionId: baseline.snapshot_session_id, snapshotRevision: baseline.snapshot_revision, timeoutMs: 30000 }
+    const target = baseline.elements.find((element: any) => element.text === targetText)
+    assert.ok(target?.bounds, `target ${targetText} needs bounds`)
+    const [left, top, right, bottom] = target.bounds
+    const matched = await call('tap', { x: Math.floor((left + right) / 2), y: Math.floor((top + bottom) / 2), expectedState, verificationMode: 'none', responseMode: 'compact', actionTimeoutMs: 30000 })
+    evidence.scenarios.push({ name: 'matching snapshot dispatch', result: matched })
+    assert.equal(matched.success, true, JSON.stringify(matched))
+    assert.equal(matched.condition.status, 'matched')
+    const destination = await observe()
+    assert.ok(contains(destination, destinationText), `destination must contain ${destinationText}`)
+    evidence.scenarios[0].observed_destination = { snapshot_revision: destination.snapshot_revision, labels: destination.elements.map((e: any) => e.text || e.contentDescription).filter(Boolean) }
+    evidence.scenarios[0].status = 'pass'
+    const back = destination.elements.find((element: any) => element.contentDescription === 'Navigate up' || element.contentDescription === 'Back' || (element.text === 'Settings' && element.clickable))
+    assert.ok(back, 'safe back-navigation target required on destination')
+    const [bl, bt, br, bb] = back.bounds
+    const selector = back.resourceId ? { resource_id: back.resourceId } :
+      back.text ? { text: back.text } : { accessibility_id: back.contentDescription }
+    for (const responseMode of ['compact', 'debug']) {
+      const mismatch = await call('tap', { x: Math.floor((bl + br) / 2), y: Math.floor((bt + bb) / 2), expectedState, verificationMode: 'none', responseMode, actionTimeoutMs: 30000 })
+      evidence.scenarios.push({ name: `mismatch blocks back navigation (${responseMode})`, result: mismatch })
+      assert.equal(mismatch.failure_code, 'PRECONDITION_FAILED', JSON.stringify(mismatch))
+      assert.equal(mismatch.dispatch_started, false)
+      assert.equal(mismatch.delivery_status, 'not_delivered')
+      assert.ok(contains(mismatch.condition.observed, destinationText))
+      const after = await observe()
+      assert.ok(contains(after, destinationText), 'blocked back navigation must leave destination visible')
+      evidence.scenarios.at(-1).status = 'pass'
+      const journey = await call('run_journey', { responseMode, defaults: { verificationMode: 'none', actionTimeoutMs: 30000 }, steps: [
+        { id: 'destination-visible', type: 'wait', selector: { text: destinationText }, condition: 'visible', timeoutMs: 30000 },
+        { id: 'conditional-back', type: 'tap', selector, waitFor: { condition: 'visible', timeoutMs: 10000 }, expectedState },
+        { id: 'must-not-run', type: 'tap', selector, waitFor: { condition: 'visible', timeoutMs: 10000 } }
+      ] })
+      evidence.scenarios.push({ name: `conditional journey stops (${responseMode})`, result: journey })
+      assert.equal(journey.stopped_at_step_id, 'conditional-back', JSON.stringify(journey))
+      assert.equal(journey.steps[0].status, 'passed')
+      assert.equal(journey.steps[1].result.failure_code, 'PRECONDITION_FAILED')
+      assert.ok(contains(journey.steps[1].result.condition.observed, destinationText))
+      assert.equal(journey.steps[2].status, 'not_run')
+      assert.ok(contains(await observe(), destinationText))
+      evidence.scenarios.at(-1).status = 'pass'
+    }
+    evidence.status = 'pass'
+    console.log(JSON.stringify({ platform, deviceId, server: evidence.server, status: evidence.status, scenarios: evidence.scenarios.map((scenario: any) => ({ name: scenario.name, status: scenario.status })), output }, null, 2))
+  } catch (error) {
+    evidence.status = 'fail'
+    evidence.error = String(error)
+    throw error
+  } finally {
+    await writeFile(output!, JSON.stringify(evidence, null, 2))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/modul8_selector_tap.manual.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import { writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+// Explicit Modul8 fixture: run after npm run build with the Android emulator booted.
+async function run() {
+  const client = new Client({ name: 'modul8-selector-tap-verification', version: '1' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const target = { platform: 'android', deviceId: 'emulator-5554' }
+  const report: any = { verified_on: new Date().toISOString(), device: target, package: 'com.ideamechanics.modul8.dev',
+    source: 'rebuilt local MCP stdio server', build_sha256: createHash('sha256').update(readFileSync('dist/server/tool-handlers.js')).digest('hex'),
+    steps: [], status: 'UNRUN', cleanup: 'UNRUN' }
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const response: any = await client.callTool({ name, arguments: { ...target, ...args } }, undefined, { timeout: 120000 })
+    return JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+  }
+  const assertVisible = async (selector: Record<string, string>) => {
+    const result = await call('expect_element_visible', { selector, timeout_ms: 10000, poll_interval_ms: 100 })
+    assert.equal(result.success, true, `Visible fixture landmark: ${JSON.stringify(selector)}`)
+  }
+  const tap = async (text: string, condition?: string) => {
+    const args: Record<string, unknown> = { selector: { text }, verificationMode: 'none', responseMode: condition ? 'debug' : 'compact' }
+    if (condition) { args.waitFor = { condition, timeoutMs: 10000 }; args.actionTimeoutMs = 15000 }
+    const result = await call('tap_element', args)
+    report.steps.push({ selector: { text }, waitForCondition: condition ?? 'default', status: result.success ? 'PASS' : 'FAIL',
+      failure_code: result.failure_code ?? null, resolved_target: result.target?.resolved, evidence: result.evidence })
+    assert.equal(result.success, true, `tap_element ${text}: ${result.failure_code ?? result.error?.message}`)
+    assert.ok(result.evidence.dispatch_started_at_ms)
+    assert.ok(result.evidence.dispatch_completed_at_ms >= result.evidence.dispatch_started_at_ms)
+    assert.equal(result.evidence.verification_completed_at_ms, null)
+  }
+  try {
+    await client.connect(transport)
+    report.server = client.getServerVersion()
+    const launch = await call('start_app', { appId: report.package, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(launch.success, true)
+    await assertVisible({ text: 'Subscription' })
+    report.starting_state = 'Subscription'
+    await tap('FAVOURITES')
+    await assertVisible({ accessibility_id: 'Favourites' })
+    await tap('GENER8')
+    await assertVisible({ text: 'Personalised breathing' })
+    await tap('SETTINGS', 'exists')
+    await assertVisible({ text: 'Subscription' })
+    await tap('FAVOURITES', 'visible')
+    await assertVisible({ accessibility_id: 'Favourites' })
+    await tap('SETTINGS')
+    await assertVisible({ text: 'Subscription' })
+    report.cleanup = 'PASS: restored Subscription; no settings, account data, favourites or sessions changed; no streams or screenshots created'
+    report.status = 'PASS'
+  } catch (error) {
+    report.status = 'FAIL'; report.error = String(error)
+    throw error
+  } finally {
+    writeFileSync('docs/specs/022-correlated-evidence/modul8-selector-fix-evidence.json', JSON.stringify(report, null, 2) + '\n')
+    console.log(JSON.stringify({ status: report.status, server: report.server, device: target, steps: report.steps.map((s: any) => ({ selector: s.selector, condition: s.waitForCondition, status: s.status })), cleanup: report.cleanup }))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/device/manual/interact/readiness.manual.ts

@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { rmSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildReadinessFixture, readinessAppId } from '../../../fixtures/readiness-app/build.js'
+
+const arg = (name: string) => { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined }
+async function run() {
+  const platform = arg('--platform')
+  const deviceId = arg('--id')
+  const output = arg('--output')
+  assert.ok(platform === 'android' || platform === 'ios')
+  assert.ok(deviceId && output, '--id and --output are required')
+  const repository = fileURLToPath(new URL('../../../../', import.meta.url))
+  const client = new Client({ name: 'readiness-device-verification', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: [path.join(repository, 'dist/server.js')], cwd: repository, stderr: 'pipe' })
+  transport.stderr?.on('data', chunk => process.stderr.write(chunk))
+  const evidence: any = { platform, deviceId, source: 'built dist/server.js over MCP stdio', checked_at: new Date().toISOString(), scenarios: [] }
+  let fixture: ReturnType<typeof buildReadinessFixture> | undefined
+  let installed = false
+  let restoreApp: string | undefined
+  const call = async (name: string, args: any = {}) => {
+    const result = await client.callTool({ name, arguments: { platform, deviceId, ...args } }, undefined, { timeout: 120000 })
+    const item: any = result.content.find((item: any) => item.type === 'text')
+    return JSON.parse(item.text)
+  }
+  const record = (name: string, result: any) => { evidence.scenarios.push({ name, result }); return result }
+  try {
+    await client.connect(transport)
+    evidence.server = client.getServerVersion()
+    const devices = await call('list_devices', { appId: readinessAppId })
+    const device = devices.devices.find((device: any) => device.id === deviceId)
+    assert.ok(device?.simulator, 'fixture mutations require an explicitly selected simulator')
+    assert.ok(!device.appInstalled, 'refuse to replace a pre-existing fixture app')
+    if (platform === 'android') restoreApp = (await call('get_current_screen')).package
+    fixture = buildReadinessFixture(platform)
+    const install = await call('install_app', { projectType: 'native', appPath: fixture.artifact })
+    assert.equal(install.installed, true, JSON.stringify(install))
+    installed = true
+    assert.equal((await call('start_app', { appId: readinessAppId, verificationMode: 'none', responseMode: 'compact' })).success, true)
+    const tree = await call('get_ui_tree')
+    assert.equal(tree.readiness.state, 'unknown', 'single-sample tree never settles')
+    evidence.initial_tree = tree
+    const target = tree.elements.find((element: any) => element.contentDescription === 'show-loader' || element.resourceId === 'show-loader' || element.text?.toLowerCase() === 'show loader')
+    assert.ok(target?.bounds)
+    const [left, top, right, bottom] = target.bounds
+    const trigger = () => call('tap', { x: (left + right) / 2, y: (top + bottom) / 2, verificationMode: 'none', responseMode: 'compact' })
+    const stable = record('stable foreground UI', await call('get_app_readiness'))
+    assert.equal(stable.success, true, JSON.stringify(stable))
+    assert.equal(stable.readiness.state, 'settled')
+    assert.equal(stable.readiness.capabilities.unresponsive, false)
+    evidence.scenarios.at(-1).status = 'pass'
+    assert.equal((await trigger()).success, true)
+    const loading = record('controlled loader observation', await call('get_app_readiness'))
+    assert.equal(loading.readiness.state, 'loading', JSON.stringify(loading))
+    evidence.scenarios.at(-1).status = 'pass'
+    const bounded = record('bounded wait cannot claim readiness', await call('wait_for_app_ready', { timeoutMs: 100, pollIntervalMs: 100 }))
+    assert.equal(bounded.success, false)
+    assert.ok(bounded.readiness.limitations.includes('DEADLINE_EXCEEDED'))
+    assert.notEqual(bounded.readiness.state, 'unresponsive')
+    evidence.scenarios.at(-1).status = 'pass'
+    const predicate = record('visible predicate waits for loader completion', await call('wait_for_ui', { selector: { text: 'Ready' }, condition: 'visible', requireReady: true, timeout_ms: 30000, poll_interval_ms: 500 }))
+    assert.equal(predicate.status, 'success', JSON.stringify(predicate))
+    assert.equal(predicate.readiness.state, 'settled')
+    const finished = await call('get_ui_tree')
+    assert.ok(finished.elements.some((element: any) => element.text === 'Done'))
+    evidence.scenarios.at(-1).status = 'pass'
+    assert.equal((await trigger()).success, true)
+    const changed = record('changed UI settles after loader', await call('wait_for_ui_change', { requireReady: true, timeout_ms: 30000, stability_window_ms: 0 }))
+    assert.equal(changed.success, true, JSON.stringify(changed))
+    assert.equal(changed.readiness.state, 'settled')
+    evidence.scenarios.at(-1).status = 'pass'
+    const wait = record('readiness wait succeeds on settled content', await call('wait_for_app_ready', { timeoutMs: 15000 }))
+    assert.equal(wait.success, true)
+    assert.equal(wait.readiness.state, 'settled')
+    evidence.scenarios.at(-1).status = 'pass'
+    evidence.status = 'pass'
+    console.log(JSON.stringify({ platform, deviceId, status: 'pass', scenarios: evidence.scenarios.map((entry: any) => ({ name: entry.name, status: entry.status })), output }, null, 2))
+  } catch (error) { evidence.status = 'fail'; evidence.error = String(error); throw error }
+  finally {
+    if (installed) {
+      await call('terminate_app', { appId: readinessAppId }).catch(() => null)
+      try {
+        if (platform === 'android') execFileSync(process.env.ADB_PATH || path.join(process.env.HOME!, 'Library/Android/sdk/platform-tools/adb'), ['-s', deviceId!, 'uninstall', readinessAppId], { stdio: 'pipe', timeout: 30000 })
+        else execFileSync('xcrun', ['simctl', 'uninstall', deviceId!, readinessAppId], { stdio: 'pipe', timeout: 30000 })
+        evidence.cleanup = 'fixture uninstalled'
+      } catch (error) { evidence.cleanup = String(error) }
+      if (restoreApp) await call('start_app', { appId: restoreApp, verificationMode: 'none', responseMode: 'compact' }).catch(() => null)
+    }
+    if (fixture) rmSync(fixture.directory, { recursive: true, force: true })
+    await writeFile(output!, JSON.stringify(evidence, null, 2))
+    await client.close()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/fixtures/debugger-app/MainActivity.java

@@ -0,0 +1,46 @@
+package dev.mobiledebugmcp.debugfixture;
+import android.app.Activity;
+import android.os.Bundle;
+import android.widget.Button;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+
+public class MainActivity extends Activity {
+  TextView status;
+  @Override public void onCreate(Bundle saved) {
+    super.onCreate(saved);
+    LinearLayout layout = new LinearLayout(this); layout.setOrientation(1); layout.setPadding(0, 160, 0, 0);
+    status = new TextView(this); status.setText("Ready"); layout.addView(status);
+    Button button = new Button(this); button.setText("Calculate");
+    button.setOnClickListener(v -> calculate(7)); layout.addView(button);
+    Button late = new Button(this); late.setText("Late class");
+    late.setOnClickListener(v -> {
+      try { Class.forName("dev.mobiledebugmcp.debugfixture.LateWork").getDeclaredMethod("work").invoke(null); }
+      catch (Exception e) { status.setText("Late failed"); }
+    }); layout.addView(late);
+    Button noLocals = new Button(this); noLocals.setText("No locals");
+    noLocals.setOnClickListener(v -> {
+      try { Class.forName("dev.mobiledebugmcp.debugfixture.NoLocals").getDeclaredMethod("work").invoke(null); }
+      catch (Exception e) { status.setText("Metadata failed"); }
+    }); layout.addView(noLocals);
+    setContentView(layout);
+  }
+  void calculate(int seed) {
+    int known = seed + 35;
+    String longText = new String(new char[300]).replace('\0', 'x');
+    Object object = new Object();
+    int answer = increment(known); // BREAK_CALCULATE
+    status.setText("Result " + answer); // BREAK_RESULT
+  }
+  int increment(int value) {
+    int result = value + 1; // BREAK_INCREMENT
+    return result;
+  }
+}
+
+class LateWork {
+  public static void work() {
+    int local = 99; // BREAK_LATE
+    android.util.Log.i("DebugFixture", "late " + local);
+  }
+}

package/test/fixtures/debugger-app/NoLocals.java

@@ -0,0 +1,7 @@
+package dev.mobiledebugmcp.debugfixture;
+public class NoLocals {
+  public static void work() {
+    int hidden = 5; // BREAK_NO_LOCALS
+    android.util.Log.i("DebugFixture", "metadata " + hidden);
+  }
+}

package/test/fixtures/debugger-app/README.md

@@ -0,0 +1,13 @@
+# Isolated Android debugger fixture
+
+Package `dev.mobiledebugmcp.debugfixture`, built with `android:debuggable=true`
+and Java source/line/local metadata. Calculate exposes `known=42`, an increment
+call for into/over/out stepping, and a visible `Result 43` after resume. Late class
+loads a second class reflectively to check pending source breakpoints. NoLocals
+is compiled with source/line tables and no variable tables to verify explicit ART
+metadata uncertainty.
+
+Build helper uses SDK platform/build-tools 36, the existing direct javac/D8/aapt2
+pattern, ephemeral signing material and temporary output. It does not modify other
+apps or display settings. The automated journey installs/removes only this fixture
+and checks session-owned ADB forwards. See [debugger tools](../../../docs/tools/debugger.md).

package/test/fixtures/debugger-app/build.ts

@@ -0,0 +1,29 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+export const debuggerAppId = 'dev.mobiledebugmcp.debugfixture'
+export function buildDebuggerFixture() {
+  const source = path.dirname(fileURLToPath(import.meta.url))
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-debugger-fixture-'))
+  const java = process.env.JAVA_HOME ?? (existsSync('/Applications/Android Studio.app/Contents/jbr/Contents/Home') ? '/Applications/Android Studio.app/Contents/jbr/Contents/Home' : undefined)
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: directory, encoding: 'utf8', stdio: 'pipe' })
+  const sdk = process.env.ANDROID_HOME ?? path.join(process.env.HOME!, 'Library/Android/sdk')
+  const tools = path.join(sdk, 'build-tools/36.0.0')
+  const androidJar = path.join(sdk, 'platforms/android-36/android.jar')
+  const jdk = (name: string) => java ? path.join(java, 'bin', name) : name
+  mkdirSync(path.join(directory, 'classes'))
+  writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${debuggerAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:debuggable="true" android:label="Debugger fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
+  run(jdk('javac'), ['-g', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'MainActivity.java')])
+  run(jdk('javac'), ['-g:source,lines', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'NoLocals.java')])
+  run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+  run(path.join(tools, 'd8'), ['--lib', androidJar, '--output', directory, 'classes.jar'])
+  run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
+  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+  run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+  run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
+  const artifact = path.join(directory, 'Debugger.apk')
+  run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
+  return { artifact, directory }
+}

package/test/fixtures/readiness-app/MainActivity.java

@@ -0,0 +1,23 @@
+package tools.mobiledebug.readinessfixture;
+import android.app.Activity;
+import android.os.Bundle;
+import android.os.Handler;
+import android.widget.*;
+import android.view.View;
+public class MainActivity extends Activity {
+  private int generation = 0;
+  public void onCreate(Bundle state) {
+    super.onCreate(state);
+    LinearLayout layout = new LinearLayout(this);
+    layout.setOrientation(LinearLayout.VERTICAL); layout.setPadding(32, 120, 32, 32);
+    TextView ready = new TextView(this); ready.setText("Ready"); ready.setContentDescription("ready"); layout.addView(ready);
+    TextView status = new TextView(this); status.setText("Idle"); layout.addView(status);
+    ProgressBar loader = new ProgressBar(this); loader.setVisibility(View.GONE); layout.addView(loader);
+    Button start = new Button(this); start.setText("Show loader"); start.setContentDescription("show-loader"); layout.addView(start);
+    start.setOnClickListener(view -> {
+      int current = ++generation; loader.setVisibility(View.VISIBLE); status.setText("Loading");
+      new Handler(getMainLooper()).postDelayed(() -> { if (current == generation) { loader.setVisibility(View.GONE); status.setText("Done"); } }, 12000);
+    });
+    setContentView(layout);
+  }
+}

package/test/fixtures/readiness-app/README.md

@@ -0,0 +1,12 @@
+# Readiness fixture
+
+Offline native Android/iOS simulator apps used only for explicit readiness
+verification. Ready stays visible while Show loader starts a 12-second loader;
+completion hides the loader and changes its status to Done. No permissions,
+accounts, networking, or persistence are used. These are test apps, not hierarchy
+inspection helpers.
+
+The manual helper builds them in a temporary directory with Android SDK 36 /
+build-tools 36.0.0 and the installed JDK, or the installed iOS simulator SDK and
+Clang. It installs only on an explicitly selected simulator and cleans up its
+own app and temporary artifacts afterward.

package/test/fixtures/readiness-app/build.ts

@@ -0,0 +1,37 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const readinessAppId = 'tools.mobiledebug.readinessfixture'
+export function buildReadinessFixture(platform: 'android' | 'ios') {
+  const source = path.dirname(fileURLToPath(import.meta.url))
+  const directory = mkdtempSync(path.join(tmpdir(), `mcp-readiness-${platform}-`))
+  const java = process.env.JAVA_HOME ?? (existsSync('/Applications/Android Studio.app/Contents/jbr/Contents/Home') ? '/Applications/Android Studio.app/Contents/jbr/Contents/Home' : undefined)
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: directory, encoding: 'utf8', env: { ...process.env, ...(java ? { JAVA_HOME: java } : {}) }, stdio: 'pipe' })
+  if (platform === 'ios') {
+    const sdk = run('xcrun', ['--sdk', 'iphonesimulator', '--show-sdk-path']).trim()
+    const artifact = path.join(directory, 'Readiness.app'); mkdirSync(artifact)
+    writeFileSync(path.join(artifact, 'Info.plist'), `<?xml version="1.0" encoding="UTF-8"?><plist version="1.0"><dict><key>CFBundleExecutable</key><string>Readiness</string><key>CFBundleIdentifier</key><string>${readinessAppId}</string><key>CFBundleName</key><string>Readiness fixture</string><key>CFBundlePackageType</key><string>APPL</string><key>CFBundleVersion</key><string>1</string><key>CFBundleShortVersionString</key><string>1.0</string><key>LSRequiresIPhoneOS</key><true/><key>MinimumOSVersion</key><string>18.0</string><key>UILaunchScreen</key><dict/></dict></plist>`)
+    run('xcrun', ['--sdk', 'iphonesimulator', 'clang', '-target', `${process.arch === 'arm64' ? 'arm64' : 'x86_64'}-apple-ios18.0-simulator`, '-isysroot', sdk, '-fobjc-arc', '-framework', 'UIKit', '-framework', 'Foundation', path.join(source, 'main.m'), '-o', path.join(artifact, 'Readiness')])
+    run('codesign', ['--force', '--sign', '-', artifact])
+    return { artifact, directory }
+  }
+  const sdk = process.env.ANDROID_HOME ?? path.join(process.env.HOME!, 'Library/Android/sdk')
+  const tools = path.join(sdk, 'build-tools/36.0.0')
+  const androidJar = path.join(sdk, 'platforms/android-36/android.jar')
+  const jdk = (name: string) => java ? path.join(java, 'bin', name) : name
+  mkdirSync(path.join(directory, 'classes'))
+  writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${readinessAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:label="Readiness fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
+  run(jdk('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'MainActivity.java')])
+  run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+  run(path.join(tools, 'd8'), ['--lib', androidJar, '--output', directory, 'classes.jar'])
+  run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
+  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+  run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+  run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
+  const artifact = path.join(directory, 'Readiness.apk')
+  run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
+  return { artifact, directory }
+}

package/test/fixtures/readiness-app/main.m

@@ -0,0 +1,27 @@
+#import <UIKit/UIKit.h>
+@interface ReadinessApp : UIResponder <UIApplicationDelegate>
+@property(strong, nonatomic) UIWindow *window;
+@property(strong, nonatomic) UILabel *status;
+@property(strong, nonatomic) UIActivityIndicatorView *loader;
+@property(nonatomic) NSInteger generation;
+@end
+@implementation ReadinessApp
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)options {
+  self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
+  UIViewController *controller = [UIViewController new]; controller.view.backgroundColor = UIColor.whiteColor;
+  self.window.rootViewController = controller;
+  UILabel *ready = [[UILabel alloc] initWithFrame:CGRectMake(30, 140, 300, 50)]; ready.text = @"Ready"; ready.accessibilityIdentifier = @"ready";
+  [controller.view addSubview:ready];
+  self.status = [[UILabel alloc] initWithFrame:CGRectMake(30, 200, 300, 50)]; self.status.text = @"Idle"; [controller.view addSubview:self.status];
+  self.loader = [[UIActivityIndicatorView alloc] initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleMedium]; self.loader.frame = CGRectMake(30, 260, 50, 50); [controller.view addSubview:self.loader];
+  UIButton *start = [UIButton buttonWithType:UIButtonTypeSystem]; start.frame = CGRectMake(30, 340, 300, 60);
+  [start setTitle:@"Show loader" forState:UIControlStateNormal]; start.accessibilityIdentifier = @"show-loader";
+  [start addTarget:self action:@selector(showLoader) forControlEvents:UIControlEventTouchUpInside]; [controller.view addSubview:start];
+  [self.window makeKeyAndVisible]; return YES;
+}
+- (void)showLoader {
+  NSInteger current = ++self.generation; self.status.text = @"Loading"; [self.loader startAnimating];
+  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 12 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{ if (current == self.generation) { self.status.text = @"Done"; [self.loader stopAnimating]; } });
+}
+@end
+int main(int argc, char **argv) { @autoreleasepool { return UIApplicationMain(argc, argv, nil, NSStringFromClass(ReadinessApp.class)); } }