Understand what your app is showing

Inspect the live UI hierarchy and capture screenshots to investigate layout, content, and element state in your iOS 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 pod: AnsightToolsVisualTree.

SwiftPM:

.product(name: "AnsightToolsVisualTree", package: "ansight-sdk")

CocoaPods:

pod 'AnsightToolsVisualTree'

Register the Suite

import AnsightCore
import AnsightToolsVisualTree

try AnsightRuntime.shared.registerVisualTreeTools()

Registration API

  • registerVisualTreeTools(): registers the full UIKit visual tree, screenshot, and diagnostic overlay suite.
  • .readOnly: exposes visual tree, screenshot, node inspection, and read-only overlay tools.
  • .readWrite: also exposes overlay creation, update, removal, and clearing.

Visual-Tree Providers

AnsightVisualTreeProviderRegistry always exposes the UIKit hierarchy as native. Additional UI frameworks can implement AnsightVisualTreeProvider and register their own stable source:

import AnsightToolsVisualTree

try AnsightVisualTreeProviderRegistry.register(
    customProvider,
    replaceExisting: true
)

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

Objective-C hosts can register the same model through ANSVisualTreeProvider.

Specific Concerns

  • The tools inspect the foreground UIKit scene.
  • Screenshot capture exports rendered UI content.
  • ui.get_screenshot streams bytes over the binary transfer channel; the result returns transfer metadata.
  • Node inspection can expose labels, accessibility metadata, and implementation-specific properties.
  • Overlay tools draw input-transparent diagnostic rectangles.
  • Persistent overlays created with durationMs = 0 stay visible until removed or cleared.

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

Tool Matrix

NameIdPolicyDescription
Get Visual Treeui.get_visual_treeReadReturns the current UIKit hierarchy for the foreground scene.
Get Screenshotui.get_screenshotReadCaptures a screenshot and streams bytes over binary transfer.
Inspect Nodeui.inspect_nodeReadReturns detailed metadata for one visual tree node.
Show Overlayui.show_overlayWriteDraws a diagnostic overlay.
Get Overlayui.get_overlayReadReturns one overlay.
Query Overlaysui.query_overlaysReadLists live diagnostic overlays.
Update Overlayui.update_overlayWriteUpdates an existing overlay.
Remove Overlayui.remove_overlayWriteRemoves one overlay.
Clear Overlaysui.clear_overlaysWriteClears diagnostic overlays.

Tool Details

Get Visual Tree

Use ui.get_visual_tree to capture the current hierarchy. Typical arguments include a provider source, bounds, computed-style inclusion, maximum depth, maximum nodes, and an optional root node id. The response includes a capture-local types registry referenced by node typeId values plus normalized roles, actions, state, presentation, and sibling order. See the Visual-Tree Payload Contract.

Get Screenshot

Use ui.get_screenshot for an on-demand screenshot. The app streams image bytes over ansight.file-transfer.v1; the resident host uses transferId to map the binary frames.

Inspect Node

Use ui.inspect_node with a visual tree nodeId and optional provider source to return one node, optional ancestors, optional descendants, and implementation-specific properties.

Overlay Tools

Use ui.show_overlay, ui.update_overlay, ui.remove_overlay, and ui.clear_overlays to draw and manage diagnostic overlays. Use ui.get_overlay or ui.query_overlays to inspect overlays without mutation.