mobile-debug-mcp 0.30.0 → 0.30.2

package/test/unit/interact/subtree_collection.test.ts

@@ -0,0 +1,24 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+
+async function run() {
+  console.log('Starting subtree_collection unit tests...')
+
+  const elements = [
+    { text: 'Root', resourceId: 'root-node', stable_id: 'root-stable', bounds: [0, 0, 100, 100], visible: true, enabled: true, clickable: true },
+    { text: 'Numeric child', parentId: '0', stable_id: 'numeric-child', bounds: [0, 0, 50, 50], visible: true, enabled: true, clickable: true },
+    { text: 'Resource child', parentId: 'root-node', stable_id: 'resource-child', bounds: [0, 50, 50, 100], visible: true, enabled: true, clickable: true },
+    { text: 'Stable child', parentId: 'root-stable', stable_id: 'stable-child', bounds: [50, 0, 100, 50], visible: true, enabled: true, clickable: true },
+    { text: 'Grandchild', parentId: 'resource-child', bounds: [50, 50, 100, 100], visible: true, enabled: true, clickable: true }
+  ] as any[]
+
+  const indices = (ToolsInteract as any)._collectSubtreeIndices(elements, 0)
+  assert.deepStrictEqual(indices, [0, 1, 2, 3, 4])
+
+  console.log('subtree_collection unit tests passed')
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/interact/tap_element.test.ts

@@ -84,6 +84,77 @@ async function run() {
     assert.strictEqual(disabledResult.success, false)
     assert.strictEqual(disabledResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
 
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Plain label', resourceId: 'txt_plain', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: false }
+      ]
+    })
+    const waitPlain = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Plain label' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    const plainResult = await ToolsInteract.tapElementHandler({ elementId: waitPlain.element.elementId })
+    assert.strictEqual(plainResult.success, false)
+    assert.strictEqual(plainResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'ios', id: 'ios-mock' },
+      elements: [
+        {
+          text: 'Semantic tap',
+          resourceId: 'ios_semantic_tap',
+          bounds: [10, 10, 30, 30],
+          visible: true,
+          enabled: true,
+          clickable: false,
+          semantic: {
+            is_clickable: true,
+            is_container: false,
+            supported_actions: ['tap']
+          }
+        }
+      ]
+    })
+    const iosSemanticWait = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Semantic tap' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'ios'
+    })
+    const iosSemanticTap = await ToolsInteract.tapElementHandler({ elementId: iosSemanticWait.element.elementId })
+    assert.strictEqual(iosSemanticTap.success, true)
+    assert.strictEqual(iosSemanticTap.target.resolved?.elementId, iosSemanticWait.element.elementId)
+    assert.deepStrictEqual(tapped, { platform: 'ios', x: 20, y: 20, deviceId: 'ios-mock' })
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Stable target', resourceId: 'btn_stable', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true, stable_id: 'stable-1' }
+      ]
+    })
+    const waitStable = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Stable target' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Stable target', resourceId: 'btn_stable', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true, stable_id: 'stable-2' }
+      ]
+    })
+    const stableMismatchResult = await ToolsInteract.tapElementHandler({ elementId: waitStable.element.elementId })
+    assert.strictEqual(stableMismatchResult.success, false)
+    assert.strictEqual(stableMismatchResult.failure_code, 'STALE_REFERENCE')
+
     ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock-device' },
       elements: []

package/test/unit/interact/wait_for_ui_change.test.ts

@@ -6,7 +6,18 @@ type UiTree = {
   device: { platform: 'android', id: string, osVersion: string, model: string, simulator: boolean }
   screen: string
   resolution: { width: number, height: number }
-  elements: Array<{ text: string, type: string, bounds: number[], visible: boolean }>
+  elements: Array<{
+    text: string
+    type: string
+    bounds: number[]
+    visible: boolean
+    enabled?: boolean
+    clickable?: boolean
+    stable_id?: string
+    parentId?: number
+    children?: number[]
+    state?: Record<string, unknown> | null
+  }>
   snapshot_revision: number
   captured_at_ms: number
 }
@@ -22,6 +33,21 @@ function makeTree(screen: string, revision: number): UiTree {
   }
 }
 
+function makeScopedTree(title: string, status: string, revision: number): UiTree {
+  return {
+    device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+    screen: 'Scoped',
+    resolution: { width: 1080, height: 2400 },
+    elements: [
+      { text: 'Root', type: 'FrameLayout', bounds: [0, 0, 1080, 2400], visible: true, enabled: true, stable_id: 'root', children: [1, 2] },
+      { text: title, type: 'TextView', bounds: [0, 0, 1080, 200], visible: true, enabled: true, stable_id: 'title', parentId: 0, state: { text_value: title } },
+      { text: status, type: 'TextView', bounds: [0, 200, 1080, 260], visible: true, enabled: true, stable_id: 'status', parentId: 0, state: { text_value: status } }
+    ],
+    snapshot_revision: revision,
+    captured_at_ms: 1000 + revision
+  }
+}
+
 async function runScenario({
   snapshots,
   expectedChange,
@@ -72,6 +98,62 @@ async function runScenario({
   }
 }
 
+async function runScopedScenario() {
+  const snapshots = [
+    makeScopedTree('Title', 'Status 1', 1),
+    makeScopedTree('Title', 'Status 2', 2),
+    makeScopedTree('Title Ready', 'Status 2', 3),
+    makeScopedTree('Title Ready', 'Status 2', 4)
+  ]
+
+  const originalGetUITreeHandler = (ToolsObserve as any).getUITreeHandler
+  const originalSetTimeout = globalThis.setTimeout
+  const originalDateNow = Date.now
+  let now = 0
+  let calls = 0
+
+  try {
+    ;(Date as any).now = () => now
+    ;(globalThis as any).setTimeout = (callback: (...args: any[]) => void) => {
+      now += 1
+      callback()
+      return 0
+    }
+
+    ;(ToolsObserve as any).getUITreeHandler = async () => snapshots[Math.min(calls++, snapshots.length - 1)]
+
+    const resolution = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Title' },
+      condition: 'exists',
+      timeout_ms: 1000,
+      poll_interval_ms: 1,
+      platform: 'android',
+      deviceId: 'mock'
+    })
+
+    const targetId = resolution?.element?.elementId
+    assert.ok(targetId)
+
+    calls = 0
+    now = 0
+    const result = await ToolsInteract.waitForUIChangeHandler({
+      platform: 'android',
+      deviceId: 'mock',
+      expected_change: 'text_change',
+      scope: 'subtree',
+      target: targetId,
+      timeout_ms: 2000,
+      stability_window_ms: 1
+    })
+
+    return { result, targetId, calls }
+  } finally {
+    ;(ToolsObserve as any).getUITreeHandler = originalGetUITreeHandler
+    ;(globalThis as any).setTimeout = originalSetTimeout
+    ;(Date as any).now = originalDateNow
+  }
+}
+
 async function run() {
   const success = await runScenario({
     snapshots: [makeTree('Loading', 1), makeTree('Loaded', 2)],
@@ -109,6 +191,15 @@ async function run() {
   assert.strictEqual(defaultWindow.calls, 4)
   assert.deepStrictEqual(defaultWindow.delays, [300, 300, 300])
 
+  const scoped = await runScopedScenario()
+  assert.strictEqual(scoped.result.success, true)
+  assert.strictEqual(scoped.result.scope, 'subtree')
+  assert.strictEqual(scoped.result.target, scoped.targetId)
+  assert.strictEqual(scoped.result.observed_change, 'text_change')
+  assert.strictEqual(scoped.result.change_summary?.added_elements, 0)
+  assert.strictEqual(scoped.result.change_summary?.removed_elements, 0)
+  assert.strictEqual(scoped.result.stability_state, 'stable')
+
   const resetWindow = await runScenario({
     snapshots: [makeTree('Loading', 1), makeTree('Loaded', 2), makeTree('Loaded-again', 3), makeTree('Loaded-again', 4), makeTree('Loaded-again', 5)],
     expectedChange: 'text_change',

package/test/unit/observe/snapshot_metadata.test.ts

@@ -0,0 +1,67 @@
+import assert from 'assert'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+
+async function run() {
+  console.log('Starting snapshot_metadata unit tests...')
+
+  resetSnapshotMetadataForTests()
+
+  const deviceKey = 'android:mock'
+  const first = deriveSnapshotMetadata(deviceKey, {
+    screen: 'Home',
+    resolution: { width: 100, height: 200 },
+    elements: [
+      {
+        text: 'Alpha',
+        contentDescription: null,
+        resourceId: 'row_1',
+        type: 'TextView',
+        clickable: false,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 10, 10],
+        state: null,
+        stable_id: 'stable-row'
+      }
+    ]
+  }, 'ui_tree')
+
+  assert.strictEqual(first.snapshot_revision, 1)
+  assert.strictEqual(first.snapshot_delta, null)
+
+  const second = deriveSnapshotMetadata(deviceKey, {
+    screen: 'Home',
+    resolution: { width: 100, height: 200 },
+    elements: [
+      {
+        text: 'Beta',
+        contentDescription: null,
+        resourceId: 'row_1',
+        type: 'TextView',
+        clickable: false,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 10, 10],
+        state: null,
+        stable_id: 'stable-row'
+      }
+    ]
+  }, 'ui_tree')
+
+  assert.strictEqual(second.snapshot_revision, 2)
+  assert.deepStrictEqual(second.snapshot_delta, {
+    previous_snapshot_revision: 1,
+    added_elements: 0,
+    removed_elements: 0,
+    mutated_elements: 1,
+    total_elements: 1
+  })
+
+  resetSnapshotMetadataForTests()
+  console.log('snapshot_metadata unit tests passed')
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

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

@@ -70,6 +70,10 @@ async function run() {
   const adjustControl = toolDefinitions.find((tool) => tool.name === 'adjust_control')
   assert(adjustControl, 'adjust_control should be registered')
   assert.deepStrictEqual((adjustControl as any).inputSchema.required, ['targetValue'])
+  assert.deepStrictEqual((adjustControl as any).inputSchema.oneOf, [
+    { required: ['selector'] },
+    { required: ['element_id'] }
+  ])
   assert.strictEqual((adjustControl as any).inputSchema.properties.targetValue.type, 'number')
   assert.match((adjustControl as any).description, /numeric control value/i)
   assert.match((adjustControl as any).description, /expect_state/i)

package/skills/rfc-review/SKILL.md

@@ -1,52 +0,0 @@
-# RFC Review skill
-
-name: rfc-review
-version: 0.1.1
-summary: Reusable workflow for reviewing RFCs/specs in this repository with a consistent readiness rubric and output template.
-
-# Purpose
-Help an agent review an RFC for clarity, implementation readiness, and alignment with the current codebase. Use a common template so reviews stay consistent across documents and reviewers.
-
-# Activation conditions
-Activate when an agent needs to:
-- review a new or revised RFC
-- assess whether an RFC is implementation-ready
-- identify whether feedback is an RFC issue or an implementation issue
-- compare a spec against the current `src/` contract surface and docs
-
-# Surface area (actions)
-- locate-rfc
-- compare-against-code
-- assess-contract-completeness
-- classify-gaps
-- produce-review
-
-# Core guidance
-1. Read the RFC first, then compare it against the relevant code, docs, and tests.
-2. Separate **spec gaps** from **implementation gaps**.
-3. Check for: problem clarity, scope boundaries, explicit contracts, acceptance criteria, non-goals, and consistency with existing behavior.
-4. Prefer precise feedback that names the missing contract, unclear rule, or inconsistent behavior.
-5. Use the shared review template in `references/rfc-review-template.md` for the final output.
-6. If the RFC is not ready, say exactly what must be clarified before implementation can start.
-7. Classify each blocker as either a **spec gap** or an **implementation contract gap** and stop at that boundary.
-
-# Inputs & outputs
-- review-rfc(input: { rfcPath, relatedPaths?, focusAreas? }) -> { verdict, risks, specGaps, implementationGaps, recommendations }
-- compare-against-code(input: { rfcPath, codePaths[] }) -> { matches, mismatches, notes }
-- produce-review(input: { rfcPath, findings[] }) -> { summary, verdict, checklist, nextStep }
-
-# Failure handling
-- If the RFC file is missing, stop and report the missing path explicitly.
-- If the RFC is ambiguous, classify each concern as either "spec" or "implementation" instead of blending them.
-- If the review cannot be grounded in the current repo, state that the RFC is not reviewable yet.
-
-# Progressive disclosure
-- Keep this file short.
-- Load the reference template only when writing the final review.
-
-# References
-- `references/rfc-review-template.md` — standard review format and verdict rubric
-- `references/rfc-review-checklist.md` — questions to apply while reviewing an RFC
-
-# License
-Same as repository (MIT).

package/skills/rfc-review/references/rfc-review-checklist.md

@@ -1,12 +0,0 @@
-# RFC Review Checklist
-
-Ask these questions while reviewing:
-
-1. Is the problem statement specific and grounded in current failures?
-2. Are non-goals explicit?
-3. Are contracts concrete enough to implement?
-4. Are acceptance criteria testable?
-5. Does the RFC define the source of truth for new fields or behaviors?
-6. Does it match existing code paths and public tool surfaces?
-7. Can each open concern be classified as a spec issue or an implementation issue?
-8. Is the RFC ready to implement without further interpretation?

package/skills/rfc-review/references/rfc-review-template.md

@@ -1,28 +0,0 @@
-# RFC Review Template
-
-Use this structure for every RFC review:
-
-## Verdict
-- Ready / Needs clarification / Needs implementation contract / Not ready
-
-## Summary
-- One short paragraph on the RFC's current quality.
-
-## What is good
-- List the strongest parts of the RFC.
-
-## Issues
-For each issue, include:
-- **Type:** spec / implementation / implementation contract / doc
-- **Severity:** low / medium / high
-- **Why it matters:** one sentence
-- **Fix:** exact change needed
-
-## Missing contract surfaces
-- List any API shapes, response fields, state transitions, or invariants that are still undefined.
-
-## Codebase alignment
-- Note whether the RFC matches current `src/`, docs, and tests.
-
-## Next step
-- State the smallest next action needed to move the RFC forward.