AXedocs
Install

Output & Errors

AXe prints short text by default, one JSON result with --output json, and a full receipt with --verbose. Simulators and devices share one set of typed error codes.

Text output#

Without --output, commands print text:

  • Commands that read or change state print that state in a few lines: displays, settings, hinge, rotate, doctor, shutdown, clipboard copy.
  • Input commands print nothing on success, except tap, slider and batch, which print a ✓ … completed successfully line.
  • screenshot and record-video print the file path.
  • describe-ui prints the accessibility tree as JSON.
  • A failure prints Error: <message> to stderr and exits nonzero.

JSON output#

Put --output json before the command for one axe.output.command-result object on stdout:

text
$ axe --output json screenshot --udid "$UDID" --output shot.png
{"command":"screenshot","data":{"result":{"path":"/…/shot.png","pixelHeight":2868,"pixelWidth":1320}},"didError":false,"nextSteps":[],"schema":"axe.output.command-result","schemaVersion":"1"}

$ axe --output json tap --id no-such-element --udid "$UDID"
{"command":"tap","data":{},"didError":true,"error":{"code":"elementNotFound","message":"No accessibility element matched --id 'no-such-element'. …"},"nextSteps":[],"schema":"axe.output.command-result","schemaVersion":"1"}
FieldMeaning
schema, schemaVersionaxe.output.command-result, version 1.
commandThe full command path, such as settings status-bar set.
didErrortrue on failure; the process also exits nonzero.
data.resultThe command's typed result. Input commands return {outcome: "completed"}; media commands return {path, pixelWidth, pixelHeight, frames?}.
error{code, message}, present exactly when didError is true.
nextStepsSuggestions for a person. Their wording can change.

Branch on error.code, never on messages or nextSteps. A failure never repeats input. Ignore fields you do not know: AXe can add fields within a schema version.

--output means two things

Before the command, --output text|json picks the result format. After screenshot and record-video, --output is still the file path. Use both: axe --output json screenshot --udid "$UDID" --output shot.png. stream-video refuses an output format, because its stdout carries frames.

Agent mode (--agent) prints JSON by default, as an axe.output.agent-result object; --output text prints the same result compactly. See Agent Mode.

Verbose receipts#

--verbose prints the full receipt where AXe owns the input or capture: context reads, target checks, delivery counts and cleanup evidence. It only adds detail. The exit status and the error code are the same with and without it. Parse it only when a check needs that evidence.

Error codes#

CodeMeaning
invalidArgumentsOptions or values are wrong, including characters type cannot send. Nothing was sent.
targetNotFound, notBootedNo simulator or device has the UDID, or the simulator is shut down.
busy, timeout, interruptedAnother AXe command holds the device, a deadline passed, or a signal stopped the command.
elementNotFound, ambiguousElement, elementNotHittableA selector matched nothing, several elements, or an element without a usable frame.
rejectedBeforeInput, inputFailed, inputUnavailableInput was refused before sending, stopped after some input, or AXe could not reach the input service.
cleanupUncertain, quarantinedA touch or key may still be held. Input stays blocked until you check the device.
screenChanged, screensDidNotSettle, bootChangedThe screen or boot changed under the command.
captureFailed, outputFailed, readFailed, xcodeUnavailableCapture, the output file, a state read, or the selected Xcode failed.
actionOutcomeUnknownA shutdown or clipboard copy may have happened but could not be confirmed.
unsupportedOnDevice, settingUnsupportedThe target does not offer this command or setting.
commandFailedAnything else.

Feature-specific codes are listed on their pages:

  • iPhone Duo: noHinge, hingeUnavailable, displayUnavailable, rotationFailed. See iPhone Duo.
  • Physical devices: notPaired, developerModeDisabled, deviceNotConnected, developerDiskImageUnavailable, deviceLocked, screenshotServiceUnavailable, rotationLocked, rotationUnconfirmed, displayOrientationMismatch, deviceStreamReplaced. See Physical iPhone & iPad.
  • Settings: settingFailed. See Device Settings.
  • Agent mode: targetCovered, keyboardCovered, targetChanged, snapshotExpired and more. See Agent Mode.

Quarantine#

If AXe cannot confirm that a touch or key was released, it fails with cleanupUncertain and records a quarantine for that simulator. Every later input command fails with quarantined until you check the device and delete the record file named in the error. Nothing is replayed.

JSON Schemas#

JSON Schema (2020-12) files are in the repository's schemas/ directory:

FileDescribes
axe.output.command-result.v1.schema.jsonThe command result envelope.
axe.output.command-payloads.v1.schema.jsonEach command's data.result, in $defs, keyed by the full command path.
axe.output.agent-result.v1.schema.jsonAgent results with --view full.
axe.output.agent-result.v2.schema.jsonAgent results with --view reading or navigation.

Receipts printed by --verbose are not described by a schema.