AXedocs
Install

Batch Automation

Run several input steps in order in one AXe command: one process, one input session, and selector waiting between steps.

axe batch is for flows where the next step does not need to look at the result of the previous one. One call replaces many separate commands, which matters for scripts and especially for agents. Agents should use the JSON form, batch --agent, which checks every target.

Steps#

Give exactly one source: repeated --step, --file or --stdin.

shell
axe batch --udid "$UDID" \
  --step "tap --id EmailField" \
  --step "type 'cam@example.com'" \
  --step "key 40"

axe batch --file login.steps --udid "$UDID"
cat login.steps | axe batch --stdin --udid "$UDID"

In a file or on stdin, put one step per line; blank lines and # comments are ignored.

text
# login.steps
tap --id EmailField --wait-timeout 5
type "cam@example.com"
tap --id PasswordField
type "correct-horse-battery-staple"
key 40
sleep 1
gesture scroll-down

Each line is a step, not a full axe command. Keep --udid on the axe batch command; a step with its own --udid is rejected.

Supported steps#

StepNotes
tapPoint or selector, with --tap-style, --wait-timeout and --element-type.
swipePoints in the current orientation.
gesturePresets and coordinate gestures, except two-finger-swipe.
drawOne-finger strokes.
touchDown and up, with --delay.
typeUses the batch's typing settings.
buttonHardware buttons, with --duration.
key, key-sequence, key-comboHID key codes.
sleep <seconds>A wait on the host, between steps.

screenshot, describe-ui, video, slider, drag, settings and discovery commands are not batch steps; run them on their own. With --input-mode selected, a batch also accepts drag and slider --endpoint steps.

Failures#

Steps run in order in one input session. A failure stops later steps, and earlier steps are not undone. On a simulator, --continue-on-error runs the remaining steps after a failed one and reports the failures at the end; on the iPhone Duo the batch still stops after a screen change or an input failure. On a physical device a failed step keeps its own error code.

Success prints ✓ Batch completed successfully (N steps).

Batch options#

OptionDefaultEffect
--wait-timeout <s>0How long selector taps wait for their element to appear.
--poll-interval <s>0.25Seconds between accessibility reads while waiting.
--ax-cache perBatch|perStep|noneperBatchWhen selector taps reuse the accessibility tree. Use perStep for flows that change screens.
--tap-style automatic|simulator|physicalautomaticDefault style of tap steps. A step's own --tap-style wins.
--type-submission chunked|compositechunkedHow type steps send their key events.
--type-chunk-size <n>200Key events per chunk with chunked.
--continue-on-erroroffSimulators: run the remaining steps after a failure.
--verboseoffLog progress to stderr; with selected input, print each step's JSON receipt instead.

Multi-screen flows#

Use --wait-timeout instead of fixed sleeps when the next screen has a selector to wait for:

shell
axe batch --udid "$UDID" --wait-timeout 5 --ax-cache perStep \
  --step "tap --id LoginButton" \
  --step "tap --id WelcomeBanner" \
  --step "tap --label 'Continue'"

Coordinate steps do not wait. For custom-drawn UI, add a sleep step.

Physical devices#

Batches work on iPhones and iPads with the hardware UDID. A device batch can hold a contact across steps and releases it when the batch ends. It refuses input after its own button lock step, and checks the lock state again before input that follows a quiet gap of 25 seconds or more.

Agent batches#

batch --agent takes a JSON document of 1 to 8 tap or type steps, all naming refs from one snapshot. AXe checks every ref before the first input, checks each target again before its step, and returns the new screen at the end.

shell
axe batch --agent --view navigation --udid "$UDID" --steps-json '{"snapshotID":"<SNAPSHOT_ID>","steps":[
  {"action":"type","ref":"e7","text":"Ada","focus":true},
  {"action":"type","ref":"e9","text":"Lovelace","focus":true},
  {"action":"tap","ref":"e12"}
]}'

Use it to fill a form, toggle several switches or pick options on one screen. See Agent Mode.

What a batch does not do#

  • It does not check the app's response. Read the screen after the batch, or use batch --agent.
  • It does not capture screenshots or video.
  • It does not retry a step beyond selector polling, and it never replays input.