Skip to main content
Accessibility tree bound to a window (or, on macOS, an application). Provides snapshot, search, and ref-based actions.

​
Constructor

​
Returns

AccessibilityTree

​
Properties

​
string
required
Get the window title (empty when it cannot be resolved).For an application-scoped tree (macOS fromInstance) this is the title of the application’s first window.

​
Methods

​
activate()

Invoke/click an element (button, link, menuitem).

​
Parameters

​
number
required

​
clearRefs()

Clear all stored element refs.

​
expandCollapse()

Expand or collapse a dropdown or tree item.

​
Parameters

​
number
required

​
find()

Search the tree using the chosen traversal order.
  • order – TraversalOrder.DepthFirst or TraversalOrder.BreadthFirst
  • role – keep nodes whose ARIA role equals this value (e.g. AriaRole.Button, AriaRole.TabList, AriaRole.MenuBar). Cross-platform ARIA roles, not the platform-native UIA.ControlType.* / AX* / AT-SPI.Role.* vocabulary.
  • name – keep nodes whose title or description contains this string
  • visible_only – skip invisible nodes (default false)
  • max_results – stop after this many matches (uses .take())
  • collapse_structural – hoist empty structural wrappers (for example Pane / Group / Custom / Document on Windows, AXGroup / AXGenericGroup / AXUnknown on macOS, AT-SPI Panel / Filler / Section on Linux) out of the walk so role searches do not hit unnamed containers (default false)
Clears existing refs; returned nodes carry refId values usable with action methods (activate, setValue, …).

​
Parameters

​
TraversalOrder
required
​
null | AriaRole
​
null | string
​
null | boolean
​
null | number
​
null | boolean

​
Returns

AccessibilityNodeJs[]

​
findByDescription()

Find every node whose overallDescription (AXNodeSynthetic::summary_with_context) is exactly equal to description, walked in pre-order depth-first. Clears existing refs; returned nodes carry refId values usable with the action methods (activate, setValue, …).

​
Parameters

​
string
required

​
Returns

AccessibilityNodeJs[]

​
focusElement()

Focus an element (brings window to foreground).

​
Parameters

​
number
required

​
fromInstance()

Create an accessibility tree bound to a running application instance (from [Machine.foregroundApp], [App.open], …). The instance carries its machine, so the tree targets whatever machine — local desktop or Android — the instance came from. The target is resolved once at construction time — subsequent snapshots keep targeting it even if the user switches away. Scope differs by platform (historical behavior): for a local instance on macOS the tree covers the whole application (every window plus the app menu bar); everywhere else it covers the instance’s first visible top-level window (Android: the app’s first live task). Use [AccessibilityTree.fromWindow] for guaranteed window scoping.

​
Parameters

​
Instance
required

​
Returns

AccessibilityTree

​
fromWindow()

Create an accessibility tree scoped to a single window. Unlike [AccessibilityTree.fromInstance] — which on macOS scopes to the whole application (every window plus the app menu bar) — this scopes to exactly the given window’s subtree on every platform. Use it to measure “is this element unique within this window”, or to snapshot / act on one window of a multi-window app. The window handle stores a persistent identity, so each snapshot re-resolves fresh data for that same window; the handle can go stale if the window is destroyed and recreated.

​
Parameters

​
Window
required

​
Returns

AccessibilityTree

​
getBounds()

Get the live bounding box of an element.

​
Parameters

​
number
required

​
Returns

BoundingBox

​
getSupportedActions()

Get the list of supported actions for an element.

​
Parameters

​
number
required

​
Returns

string[]

​
scrollIntoView()

Scroll an element into view.

​
Parameters

​
number
required

​
select()

Select a tab, radio button, or list item.

​
Parameters

​
number
required

​
setValue()

Set the text value of an element (textbox, combobox).

​
Parameters

​
number
required
​
string
required

​
showMenu()

Open an element’s context menu — the semantic equivalent of a right-click, without synthesizing pointer input, so it works on background / obscured windows (Windows ShowContextMenu, macOS AXShowMenu, Linux AT-SPI show-menu, Android long-press). The opened menu itself typically appears as the topmost / focused window even when the target window stays in the background — a user watching the desktop sees a menu pop up without having done anything. Throws when the element does not support opening a menu this way; callers can fall back to a coordinate right-click at the center of [AccessibilityTree.getBounds].

​
Parameters

​
number
required

​
snapshot()

Take a snapshot of the tree. Re-resolves the root so each call sees current data. On Windows the resolve issues a single BuildUpdatedCache IPC; the recursive walk over children and properties then stays entirely in-process, ~40× faster than walking a live root. visible_only (default false) controls whether nodes whose non-standard AXVisible attribute reads false are dropped from the result. AXVisible is a Chromium-specific extension; native macOS apps don’t expose it, so the filter only matters for browser windows. Chrome reports many web-content nodes (including AXLink) as AXVisible=false because its accessibility-tree visibility is compositor-driven, not pixel-driven — setting visible_only=true on a Chrome window will silently drop most of the page including links.

​
Parameters

​
null | boolean

​
Returns

AccessibilityNodeJs

​
toggle()

Toggle a checkbox or switch.

​
Parameters

​
number
required