android_uiautomator_wait
Wait for a specific UI element to appear on an Android device by its resource ID, with configurable timeout for automated testing and interaction.
Instructions
Wait for a UI element to appear by resource ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| resourceId | Yes | Resource ID of the element to wait for | |
| timeoutMs | No | Maximum time to wait in milliseconds (default: 5000) | |
| deviceSerial | No | Specific device serial number to target (optional) |
Implementation Reference
- src/handlers.ts:348-374 (handler)The primary handler function that executes the android_uiautomator_wait tool. It validates input arguments and delegates to the ADB wrapper's waitForElement method to perform the polling logic.
export async function uiautomatorWaitHandler( adb: ADBWrapper, args: any ): Promise<{ content: Array<{ type: string; text: string }> }> { const { resourceId, timeoutMs = 5000, deviceSerial } = args as UIAutomatorWaitArgs; if (!resourceId || typeof resourceId !== 'string') { throw new Error('Invalid resource ID: resourceId must be a non-empty string'); } try { const found = await adb.waitForElement(resourceId, timeoutMs, deviceSerial); return { content: [ { type: 'text', text: found ? `Element with resource-id "${resourceId}" found within ${timeoutMs}ms` : `Element with resource-id "${resourceId}" not found after ${timeoutMs}ms`, }, ], }; } catch (error) { throw new Error(`UIAutomator wait failed: ${error instanceof Error ? error.message : String(error)}`); } } - src/adb-wrapper.ts:533-562 (helper)Core helper method in ADBWrapper that implements the polling logic: repeatedly dumps the UI hierarchy using uiautomator and checks for the presence of the specified resourceId until timeout.
async waitForElement( resourceId: string, timeoutMs: number = 5000, deviceSerial?: string ): Promise<boolean> { const device = await this.getTargetDevice(deviceSerial); const startTime = Date.now(); const pollInterval = 500; // Check every 500ms while (Date.now() - startTime < timeoutMs) { try { const hierarchyFile = '/sdcard/window_dump.xml'; await this.exec(['shell', 'uiautomator', 'dump', hierarchyFile], device); const { stdout } = await this.exec(['shell', 'cat', hierarchyFile], device); await this.exec(['shell', 'rm', hierarchyFile], device); if (stdout.includes(`resource-id="${resourceId}"`)) { return true; } } catch (error) { // Continue polling on error } // Wait before next poll await new Promise(resolve => setTimeout(resolve, pollInterval)); } return false; } - src/index.ts:208-229 (schema)The JSON schema definition for the tool's input parameters, registered in the ListTools response.
name: 'android_uiautomator_wait', description: 'Wait for a UI element to appear by resource ID', inputSchema: { type: 'object', properties: { resourceId: { type: 'string', description: 'Resource ID of the element to wait for', }, timeoutMs: { type: 'number', description: 'Maximum time to wait in milliseconds (default: 5000)', default: 5000, }, deviceSerial: { type: 'string', description: 'Specific device serial number to target (optional)', }, }, required: ['resourceId'], }, }, - src/index.ts:480-481 (registration)Tool handler registration in the switch statement within the CallToolRequest handler.
case 'android_uiautomator_wait': return await uiautomatorWaitHandler(this.adb, args); - src/handlers.ts:49-53 (schema)TypeScript interface defining the expected arguments for the handler function.
interface UIAutomatorWaitArgs { resourceId: string; timeoutMs?: number; deviceSerial?: string; }