hierarchy

name	hierarchy
description	Dump and analyze the live accessibility hierarchy for the current simulator screen. Use to debug why a test can't find an element, inspect what identifiers are set, or understand the element tree before writing flows.
argument-hint	[--screen=<ViewName>] [--filter=<text>] [--json]

Swift Assist: Hierarchy

Dump the live accessibility hierarchy from the running app and analyze it. Use this when a test can't find an element, when you want to verify that .accessibilityIdentifier() modifiers are applied correctly, or when you're planning a new flow and need to know what the hierarchy actually exposes.

Usage

/swift-assist:hierarchy
/swift-assist:hierarchy --screen=LandmarkDetail
/swift-assist:hierarchy --filter=button
/swift-assist:hierarchy --json

Command Options

• --screen=<ViewName>: Navigate to a specific screen first before dumping (uses computer use)
• --filter=<text>: Filter output to elements whose name, label, or identifier contains this text
• --json: Output raw JSON instead of formatted tree

What This Command Does

Phase 1: Verify Runner

Check that the Grantiva runner is active:

grantiva runner start --bundle-id <BUNDLE_ID> --simulator "<SIMULATOR>"

Read bundle ID and simulator from grantiva.yml. If the runner fails to start, stop and tell the user to run /swift-assist:init first.

Phase 2: Navigate to Screen (if --screen provided)

If --screen was provided, use computer use to navigate to that screen before dumping the hierarchy. This may involve tapping tabs, navigation links, or buttons to reach the target view.

Phase 3: Dump Hierarchy

grantiva runner dump-hierarchy

This queries the live XCUITest element tree from the running app.

Phase 4: Parse and Display

Format the raw hierarchy into a readable tree. Show element type, label, name (accessibility identifier), and value for each element:

[XCUIElementTypeApplication] label="MyApp"
  [XCUIElementTypeWindow]
    [XCUIElementTypeTabBar] label="Tab Bar"
      [XCUIElementTypeButton] name="home-tab" label="Home"
      [XCUIElementTypeButton] name="settings-tab" label="Settings"
    [XCUIElementTypeScrollView]
      [XCUIElementTypeStaticText] label="Welcome"
      [XCUIElementTypeButton] name="get-started-button" label="Get Started"
      [XCUIElementTypeButton] label="Sign In"  ← no identifier

Mark elements without an accessibility identifier with ← no identifier.

If --filter was provided, show only matching elements and their ancestors for context.

Phase 5: Summarize

After the tree, print a summary:

Summary
=======
Total interactive elements:  12
With identifiers:             9  (75%)
Without identifiers:          3

Elements without identifiers:
  [XCUIElementTypeButton] label="Sign In"
  [XCUIElementTypeTextField] label="Email"
  [XCUIElementTypeSwitch] label="Remember Me"

Run /swift-assist:doctor --fix to add missing identifiers.

Phase 6: Highlight Testability Issues

Call out elements that tests commonly have trouble with:

• Tab bar buttons: explain that identifiers go on content, not the tab itself
• Navigation bar buttons: often use label not name for tapping
• Cells in lists: may need identifiers on inner elements, not the cell container

Output Modes

Default (formatted tree): Best for human reading and debugging.

--json: Outputs the raw JSON from grantiva runner dump-hierarchy for piping or programmatic use.

Important Rules

1. Always show the full tree - do not truncate unless the user asks
2. Clearly mark elements missing identifiers
3. If --screen navigation fails, dump the hierarchy of wherever the app currently is and note that navigation didn't reach the target
4. Do not modify source code