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.
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.
# 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-downEach 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
| Step | Notes |
|---|---|
tap | Point or selector, with --tap-style, --wait-timeout and --element-type. |
swipe | Points in the current orientation. |
gesture | Presets and coordinate gestures, except two-finger-swipe. |
draw | One-finger strokes. |
touch | Down and up, with --delay. |
type | Uses the batch's typing settings. |
button | Hardware buttons, with --duration. |
key, key-sequence, key-combo | HID 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
| Option | Default | Effect |
|---|---|---|
--wait-timeout <s> | 0 | How long selector taps wait for their element to appear. |
--poll-interval <s> | 0.25 | Seconds between accessibility reads while waiting. |
--ax-cache perBatch|perStep|none | perBatch | When selector taps reuse the accessibility tree. Use perStep for flows that change screens. |
--tap-style automatic|simulator|physical | automatic | Default style of tap steps. A step's own --tap-style wins. |
--type-submission chunked|composite | chunked | How type steps send their key events. |
--type-chunk-size <n> | 200 | Key events per chunk with chunked. |
--continue-on-error | off | Simulators: run the remaining steps after a failure. |
--verbose | off | Log 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:
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.
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.