wait_for_element
Wait for a UI element to appear on screen within a specified timeout. Use this tool after navigation, loading screens, or animations to ensure elements are present before interaction.
Instructions
Wait for a UI element to appear on screen within a timeout period. Useful after navigation, loading screens, or animations. Polls the UI tree at regular intervals until the element is found.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | Element selector to wait for | |
| timeout_ms | No | Maximum wait time in milliseconds (default: 10000) | |
| device_id | No | Device serial number |
Implementation Reference
- The core implementation of the waitForElement function, which polls the UI tree until the element is found or a timeout occurs.
export async function waitForElement( selector: ElementSelector, timeoutMs: number = 10000, pollIntervalMs: number = 1000, deviceId?: string ): Promise<FoundElement> { const resolved = await deviceManager.resolveDeviceId(deviceId); const startTime = Date.now(); while (Date.now() - startTime < timeoutMs) { try { const elements = await findElements(selector, resolved); if (elements.length > 0) { log.info('Element found after waiting', { selector, elapsedMs: Date.now() - startTime, deviceId: resolved, }); return elements[0]; } } catch (error) { // UI tree dump might fail transiently; keep trying log.debug('UI tree dump failed during wait, retrying...', { error: error instanceof Error ? error.message : String(error), }); } await new Promise(resolve => setTimeout(resolve, pollIntervalMs)); } const selectorStr = Object.entries(selector) .map(([k, v]) => `${k}="${v}"`) .join(', '); throw new TimeoutError(`waitForElement(${selectorStr})`, timeoutMs); } - src/controllers/ui-tools.ts:134-155 (registration)Tool registration and handler wrapper for wait_for_element in the controller layer.
server.registerTool( 'wait_for_element', { description: 'Wait for a UI element to appear on screen within a timeout period. Useful after navigation, loading screens, or animations. Polls the UI tree at regular intervals until the element is found.', inputSchema: { selector: selectorSchema.describe('Element selector to wait for'), timeout_ms: z.number().optional().default(10000).describe('Maximum wait time in milliseconds (default: 10000)'), device_id: z.string().optional().describe('Device serial number'), }, }, async ({ selector, timeout_ms, device_id }) => { return await metrics.measure('wait_for_element', device_id || 'default', async () => { try { const element = await waitForElement(selector as ElementSelector, timeout_ms, undefined, device_id); return { content: [{ type: 'text' as const, text: JSON.stringify({ success: true, found: true, element, }, null, 2),