xcui Reference (Scriptable Simulator UI & Accessibility Testing)

Complete reference for xcui, the Axiom-bundled CLI that makes iOS-simulator UI and accessibility testing scriptable for coding harnesses. It owns the test-harness semantics AXe and simctl lack — waiting on conditions, asserting on the accessibility tree, and toggling accessibility settings — and delegates input (tap/type/swipe) to AXe, which injects real HID touch. Every subcommand emits a single pretty-printed JSON object with a tool/version envelope, and exit codes drive pass/fail in scripts.

When to Use This Reference

Use this reference when:

• Looking up xcui doctor / wait / assert / a11y set / a11y reset subcommand flags
• Interpreting an exit code (0 pass / 1 assertion-fail or wait-timeout / 2 environment error / 8 output-write error)
• Checking which accessibility toggles a11y set supports and how each is applied (native simctl ui vs defaults write + relaunch)
• Understanding how xcui auto-resolves the booted simulator and when to pass --udid
• Deciding what to drive with xcui versus what to call on axe directly (taps, typing, gestures)
• Switching between JSON (default) and --human output
• Diagnosing why a doctor run reports exit 2 (AXe missing or no booted sim)

Example Prompts

• "How do I wait for an element to appear on the simulator before asserting?"
• "How do I assert a VoiceOver label and trait on an element?"
• "How do I turn on Dynamic Type or Increase Contrast on the simulator?"
• "What does xcui doctor check, and how do I install AXe?"
• "Why did xcui assert exit 1?"
• "Why isn't my accessibility toggle taking effect until I relaunch the app?"

What's Covered

• Invocation — xcui is on PATH as a bare command (plugin bin/ is auto-resolved); run xcui <subcommand>
• doctor subcommand — verifies AXe, Homebrew, Xcode, and a booted simulator; --install runs brew install cameroncooke/axe/axe (explicit/consented, never silent); --human for prose. Always auto-resolves the booted sim
• wait subcommand — --for-element <id>, --gone <id>, or --idle, with --timeout and --poll; polls the accessibility tree until the condition holds or the deadline passes (the headless equivalent of waitForExistence)
• assert subcommand — --id <id> plus optional --label, --value, --trait, and --single; --single asserts the id resolves to exactly one element; --trait matches a bare word (button, image) against the AX role or type
• a11y set / a11y reset — the four verified toggles and how each is applied (see table below); --app <bundle-id> triggers an app relaunch for the toggles that need it
• Input via AXe — xcui does not re-wrap tap/type/swipe/touch; call axe directly for real HID input, and axe describe-ui for the raw tree xcui parses
• Output envelope & exit codes — single JSON object with tool/version first; --human for prose; exit 0 pass · 1 assertion-fail/wait-timeout · 2 environment error · 8 output-write error
• CLI grammar gotcha — Go's flag parser stops at the first positional, so always use the all-flag forms (assert --id …, not assert <id> …)

Accessibility Toggles

a11y set --toggle <name> --value <…> supports the following, all verified against the booted simulator. a11y reset clears them (deletes the defaults keys, sets content_size large, sets increase_contrast disabled).

Toggle	Mechanism	--value	Relaunch
dynamic-type	native simctl ui content_size	a size (large … accessibility-extra-extra-extra-large)	no
increase-contrast	native simctl ui increase_contrast	on / off	no
reduce-motion	defaults write com.apple.Accessibility ReduceMotionEnabled	on / off	yes (pass --app)
reduce-transparency	defaults write com.apple.Accessibility ReduceTransparencyEnabled	on / off	yes (pass --app)

voiceover, differentiate-without-color, and bold-text are not supported in v1 — they had no confirmable simulator mechanism (no native simctl ui setter, and their candidate defaults keys are not honored on the sim), so they were omitted rather than shipped unverified.

Documentation Scope

This page documents the xcui-ref reference skill — the bundled Axiom CLI for scriptable simulator UI and accessibility testing.

• For the agent that drives xcui live (set toggles, wait, assert on the tree), see the simulator-tester agent
• For static accessibility source scanning (the read-only counterpart that pairs with live validation), see the accessibility-auditor agent
• For the input primitives xcui delegates to, see AXe (Simulator Automation)
• For the /axiom:ui command wrapper, see /axiom:ui
• For the sibling bundled tools, see Console Capture (xclog) and Crash Symbolication (xcsym)