assert_element_exists

Verify UI element presence on Android screens for test assertions and conditional logic. Returns true/false without throwing errors when elements are found or missing.

Instructions

Check whether a UI element exists on the current screen. Returns true/false without throwing an error. Useful for test assertions and conditional logic.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`selector`	Yes	Element selector to check
`device_id`	No	Device serial number

Implementation Reference

src/uiautomator/element-finder.ts:165-175 (handler)

The implementation of the assertElementExists function, which attempts to find an element using findElement and returns its existence status.

export async function assertElementExists(
  selector: ElementSelector,
  deviceId?: string
): Promise<{ exists: boolean; element?: FoundElement }> {
  try {
    const element = await findElement(selector, deviceId);
    return { exists: true, element };
  } catch {
    return { exists: false };
  }
}

src/uiautomator/element-finder.ts:11-21 (schema)

The ElementSelector interface defining the valid parameters for identifying UI elements.

export interface ElementSelector {
  text?: string;
  textContains?: string;
  resourceId?: string;
  className?: string;
  contentDesc?: string;
  contentDescContains?: string;
  clickable?: boolean;
  enabled?: boolean;
  packageName?: string;
}

src/controllers/ui-tools.ts:175-194 (registration)

The registration/handler call site within the MCP tools controller where the 'assert_element_exists' tool is invoked.

'assert_element_exists',
{
  description: 'Check whether a UI element exists on the current screen. Returns true/false without throwing an error. Useful for test assertions and conditional logic.',
  inputSchema: {
    selector: selectorSchema.describe('Element selector to check'),
    device_id: z.string().optional().describe('Device serial number'),
  },
},
async ({ selector, device_id }) => {
  return await metrics.measure('assert_element_exists', device_id || 'default', async () => {
    const result = await assertElementExists(selector as ElementSelector, device_id);
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify({
          success: true,
          exists: result.exists,
          element: result.element || null,
        }, null, 2),
      }],

Android MCP Server