Axe

Step 1: Confirm runtime context

1. Identify simulator UDID target first (axe list-simulators).
2. Simulator-interaction AXe commands require --udid <UDID>. Commands like list-simulators and init do not.
3. Run axe describe-ui --udid <UDID> to inspect the full current screen. Use axe describe-ui --point <X,Y> --udid <UDID> to inspect the element at a specific coordinate. Use the output to discover available --id and --label values for selector taps and slider setting, and to confirm coordinates for coordinate-based taps.
4. Prefer selectors (tap --id / tap --label, slider --id / slider --label) over raw coordinates. Selectors are resilient to layout changes, work across device sizes, and support element waiting where documented. For UIKit UISwitch and SwiftUI Toggle rows, selector taps activate the contained switch/toggle when the match contains exactly one such control. Default tap style is automatic: switches/toggles use physical touch down/up, while normal taps use simulator tapAt.

Step 2: Choose the right command

Available commands: init, tap, slider, swipe, drag, gesture, touch, type, button, key, key-sequence, key-combo, batch, describe-ui, screenshot, record-video, stream-video, list-simulators. Run axe --help or axe <command> --help for full options.

Common examples:

axe tap --id <identifier> --udid <UDID>
axe tap --label <text> --udid <UDID>
axe tap --label 'Weather Alerts' --udid <UDID>
axe slider --id <identifier> --value 75 --udid <UDID>
axe slider --label <text> --value 40 --element-type Slider --udid <UDID>
axe drag --start-x <X1> --start-y <Y1> --end-x <X2> --end-y <Y2> --udid <UDID>
axe tap -x <X> -y <Y> --tap-style physical --udid <UDID>
axe tap -x <X> -y <Y> --udid <UDID>
axe type 'text' --udid <UDID>
axe describe-ui --udid <UDID>
axe describe-ui --point <X,Y> --udid <UDID>
axe screenshot --udid <UDID> --output screenshot.png

Step 3: Understand the execution model

Most HID commands (tap, swipe, drag, type, key, etc.) are fire-and-forget — AXe confirms the event was dispatched to the simulator but cannot verify the app actually processed it. A tap may land before a view is interactive, or during a transition. slider is the exception: it performs one selector-resolved low-level HID drag, re-reads the matched slider AXValue, and fails if the observed 0-100 value is outside tolerance. iOS slider controls quantize values to their rendered track resolution, so AXe does not retry correction gestures to chase unreachable decimals. This means:

• Always verify outcomes separately with describe-ui or screenshot when app behavior matters beyond the direct command result.
• Use --wait-timeout in batch to wait for tap elements to appear, and sleep steps or --pre-delay / --post-delay to allow animations to settle.

Step 4: Apply timing and input best practices

• Use --pre-delay / --post-delay on tap, swipe, and gesture commands for fixed delays around actions.
• Use --duration to control how long a swipe, gesture, button press, or key press lasts.
• Coordinate-based tap, swipe, drag, and touch accept coordinates from describe-ui directly; AXe detects rotated landscape simulator orientation and letterboxed landscape-only app layouts automatically.
• Use axe slider --id <identifier> --value <0-100> for sliders instead of approximating with raw swipe coordinates; it uses one calibrated low-level HID drag from the resolved slider frame/current AXValue, through the same composite touch-move path as drag, verifies the result within tolerance, and fails clearly if the observed AXValue remains outside tolerance.
• For text with shell-sensitive characters, prefer --stdin or --file over inline quotes.
• Use single quotes for inline text arguments to avoid shell expansion issues.

Step 5: Batch vs discrete commands

Prefer axe batch for multi-step flows. Batch executes every step in a single process invocation, which means:

• One tool call and one AI turn instead of many — significantly reduces agent latency and cost.
• A single HID session is reused across all steps, lowering per-step overhead.
• Steps execute sequentially — each step runs before the next is resolved, so earlier taps can trigger navigation and later selector taps will find newly appeared elements (with --wait-timeout).

Fall back to discrete commands when:

• A step's parameters depend on runtime inspection of a previous step's result (e.g. parsing describe-ui JSON to choose coordinates dynamically).
• Using slider; batch steps do not support slider verification.

Handling animations and transitions in batch:

• Use --wait-timeout <seconds> so selector taps (--id / --label) poll the accessibility tree until the element appears or the timeout expires. This is the primary mechanism for multi-screen flows.
• Use --poll-interval <seconds> to control polling frequency during waiting (default 0.25s).
• Use --ax-cache perStep when not using --wait-timeout but the UI still changes between steps — this ensures each selector tap gets a fresh accessibility snapshot rather than a stale cached one.
• Insert explicit sleep <seconds> steps when coordinate-based taps need the UI to be stable (selectors with --wait-timeout are preferred over sleep where possible).
• Keep batch output quiet by default. Add --verbose only when troubleshooting.
• Selector taps in batch share direct tap semantics, including switch/toggle activation-point handling and --tap-style automatic behavior. Use batch-level --tap-style physical|simulator as the default for tap steps, or step-level tap --tap-style ... to override one step.
• If tap --label reports multiple matches and no AXUniqueId values are exposed, fall back to tap -x/-y for that step.

Key rules:

• Use exactly one step source per run: --step, --file, or --stdin.
• Steps run in order; default is fail-fast.
• Add --continue-on-error for best-effort execution.
• Do not pass --udid inside step lines; keep it at batch level.

Step 6: Verify outcomes

Batch and individual commands are execution-focused, not assertion-focused. Always suggest verification when outcomes matter:

axe describe-ui --udid <UDID>
axe describe-ui --point <X,Y> --udid <UDID>
# or
axe screenshot --udid <UDID> --output post-state.png

Step 7: Exit criteria

Before finalising guidance, verify:

• Every simulator-interaction command includes --udid.
• Only valid AXe commands and flags are used.
• Shell quoting is correct (single quotes for literals, --stdin/--file for complex text).
• Verification is suggested as a separate step when results matter.