Reference

ui

The accessibility tree, resolved on the device: snapshots, queries and waits. Index · shared schemas · errors.

Procedure	Summary	REST	MCP tool	Stability
`ui.snapshot`	Take an accessibility snapshot with element refs. `format` defaults to `aria`.	`GET`	`ui_snapshot`	stable
`ui.query`	Resolve a locator once, with no waiting: one device round trip. The test framework's assertion polls use it.	`POST`	`ui_query`	stable
`ui.waitFor`	Wait for a locator to reach a state	`POST`	`ui_waitFor`	stable
`ui.describeAt`	Hit-test a point. Returns the node, its ancestors and the best unique locator (codegen, pick-locator, inspector). When the app's JavaScript runtime is connected (a React Native debug build launched with `devServerUrl`, or `debug.connect`), `react` also names the React components that rendered the element there, innermost first, each with the source file and line where it was written.	`GET`	`ui_describeAt`	stable

`ui.snapshot`

Take an accessibility snapshot with element refs. format defaults to aria.


REST	`GET /v1/ui/snapshot` (input as query parameters)
RPC	`/rpc/v2/ui/snapshot`
MCP	tool `ui_snapshot`; hints: read-only, idempotent
Auth	`devices:read`
Tenancy	`project`
Requires	`ui.tree`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  scope?: LocatorRoot  // default 'app'
  bundleId?: BundleId
  format?: 'aria' | 'tree' | 'both'  // default 'aria'
  includeHidden?: boolean  // default false
  maxNodes?: integer  // default 5000; ≥ 1
}

Output:

TypeScript

{
  snapshotId: SnapshotId
  takenAt: string
  aria?: string
  tree?: A11yNode
  nodeCount: integer
  truncated: boolean
}

Errors: S, APP_NOT_RUNNING, APP_CRASHED.

Named types: A11yNode, BundleId, LocatorRoot, SessionId, SnapshotId.

`ui.query`

Resolve a locator once, with no waiting: one device round trip. The test framework's assertion polls use it.


REST	`POST /v1/ui/query` (input as a JSON body)
RPC	`/rpc/v2/ui/query`
MCP	tool `ui_query`; hints: read-only, idempotent
Auth	`devices:read`
Tenancy	`project`
Requires	`ui.tree`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  locator: Locator
  limit?: integer  // default 50; 1–500
}

Output:

TypeScript

{ count: integer; matches: A11yNode[] }

Errors: S, APP_NOT_RUNNING, APP_CRASHED.

Named types: A11yNode, Locator, SessionId.

`ui.waitFor`

Wait for a locator to reach a state


REST	`POST /v1/ui/wait-for` (input as a JSON body)
RPC	`/rpc/v2/ui/waitFor`
MCP	tool `ui_waitFor`; hints: read-only, idempotent
Auth	`devices:read`
Tenancy	`project`
Requires	`ui.tree`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  locator: Locator
  state?: 'visible' | 'attached' | 'hidden' | 'detached'  // default 'visible'
  strict?: boolean  // default true
  timeoutMs?: TimeoutMs  // default 5000
}

Output:

TypeScript

{ count: integer; matches: A11yNode[] }

Errors: S, TIMEOUT, LOCATOR_STRICT_VIOLATION, APP_NOT_RUNNING, APP_CRASHED.

Named types: A11yNode, Locator, SessionId, TimeoutMs.

`ui.describeAt`

Hit-test a point. Returns the node, its ancestors and the best unique locator (codegen, pick-locator, inspector). When the app's JavaScript runtime is connected (a React Native debug build launched with devServerUrl, or debug.connect), react also names the React components that rendered the element there, innermost first, each with the source file and line where it was written.


REST	`GET /v1/ui/describe-at` (input as query parameters)
RPC	`/rpc/v2/ui/describeAt`
MCP	tool `ui_describeAt`; hints: read-only, idempotent
Auth	`devices:read`
Tenancy	`project`
Requires	`ui.tree`; `ui.describeAt`
Troupe Cloud	relayed through the host agent to the device host’s runtime
Stability	stable, since 1.0

Input:

TypeScript

{
  sessionId: SessionId
  x: number
  y: number
  scope?: LocatorRoot  // default 'app'
}

Output:

TypeScript

{
  node?: A11yNode
  ancestors: A11yNode[]
  locator?: LocatorOut
  locatorCode?: string
  unique: boolean
  react?: ReactAtPoint
}

Errors: S, APP_NOT_RUNNING.

Named types: A11yNode, LocatorOut, LocatorRoot, ReactAtPoint, SessionId.