Understand what your app is showing

Inspect the live UI hierarchy and capture screenshots to investigate layout, content, and element state in your Android app.

VisualTree tools connect what you see on screen with the elements that make up the live UI. Use hierarchy snapshots, focused node inspection, and screenshots to investigate layout or content problems.

Install

Published artifact: ai.ansight:ansight-tools-visualtree-android.

dependencies {
    debugImplementation("ai.ansight:ansight-tools-visualtree-android:latest.release")
}

Register the Suite

import ai.ansight.runtime.AnsightOptions
import ai.ansight.tools.visualtree.withVisualTreeTools

val options = AnsightOptions.createBuilder()
    .withVisualTreeTools()
    .withReadOnlyToolAccess()
    .build()

Registration API

withVisualTreeTools(): registers the visual tree, screenshot, and diagnostic overlay suite.
AndroidVisualTreeTools.create(): creates the suite tools for lower-level registration.
withReadOnlyToolAccess(): exposes visual tree, screenshot, node inspection, and read-only overlay tools.
withReadWriteToolAccess(): also exposes overlay creation, update, removal, and clearing; every overlay mutation uses Write.

Visual-Tree Providers

AndroidVisualTreeProviderRegistry always exposes the Android view hierarchy as native. Additional UI frameworks can implement AndroidVisualTreeProvider and register their own stable source:

import ai.ansight.tools.visualtree.AndroidVisualTreeProviderRegistry

AndroidVisualTreeProviderRegistry.register(
    provider = customProvider,
    replaceExisting = true,
)

The provider supplies source, displayName, getVisualTree(...), and inspectNode(...). Pass source to ui.get_visual_tree or ui.inspect_node; omitting it selects native. Responses use the shared compact visual-tree v2 contract.

Specific Concerns

The native provider captures every top-level Android window root owned by the foreground activity, including dialogs and popup windows when present.
Screenshot capture exports rendered UI content.
ui.get_screenshot streams bytes over the binary transfer channel.
Overlay removal tools use Write consistently across platforms.

Important: Calling screenshot tools will result in an FPS drop while the current frame is captured, encoded, and transferred. Avoid screenshot-heavy investigations during trend measurements unless visual evidence is required.

Tool Matrix

Name	Id	Policy	Description
`Get Visual Tree`	`ui.get_visual_tree`	`Read`	Returns the current visual hierarchy for the requested source.
`Get Screenshot`	`ui.get_screenshot`	`Read`	Captures a screenshot and streams bytes over binary transfer.
`Inspect Node`	`ui.inspect_node`	`Read`	Returns one node from the current visual tree.
`Show Overlay`	`ui.show_overlay`	`Write`	Shows a rectangular diagnostic overlay.
`Get Overlay`	`ui.get_overlay`	`Read`	Returns one diagnostic overlay.
`Query Overlays`	`ui.query_overlays`	`Read`	Lists active diagnostic overlays.
`Update Overlay`	`ui.update_overlay`	`Write`	Updates a diagnostic overlay.
`Remove Overlay`	`ui.remove_overlay`	`Write`	Removes a diagnostic overlay.
`Clear Overlays`	`ui.clear_overlays`	`Write`	Clears diagnostic overlays.

Tool Details

Use read tools for inspection and screenshots. ui.get_visual_tree and ui.inspect_node accept an optional source argument for provider selection. Their responses include a top-level types registry referenced by each node’s typeId, semantic roles and actions, automation ids, presentation data, and structural child order. See the Visual-Tree Payload Contract. Use write tools only when the session needs to create, update, remove, or clear overlays remotely.