AXe Usage Examples

This document shows how to use AXe's comprehensive HID functionality including gesture presets, delay controls, and coordinate helpers.

Basic Setup

First, get the UDID of your simulator:

# List available simulators
axe list-simulators

# Find a booted simulator and copy its UDID
# Example: B34FF305-5EA8-412B-943F-1D0371CA17FF

Install the AXe Skill

# Install into detected clients (.claude/.agents)
axe init

# Non-interactive usage: pass an explicit target
axe init --client claude

# Install into a custom destination directory
axe init --dest ~/.agents/skills

# Print the skill without writing files
axe init --print

# Remove installed skill directories
axe init --uninstall --client agents

HID Commands Overview

AXe provides comprehensive HID (Human Interface Device) functionality matching idb capabilities:

1. Text Input

# Simple text input
axe type 'Hello World!' --udid SIMULATOR_UDID

# Use single quotes for special characters
axe type 'Special chars: @#$%^&*()' --udid SIMULATOR_UDID

# From stdin (best for automation)
echo "Complex text with any characters!" | axe type --stdin --udid SIMULATOR_UDID

# From file
echo "Multi-line text content" > input.txt
axe type --file input.txt --udid SIMULATOR_UDID

2. Touch & Gestures

# Simple tap
axe tap -x 100 -y 200 --udid SIMULATOR_UDID

# Tap by accessibility element (uses describe-ui accessibility tree)
axe tap --id "Safari" --udid SIMULATOR_UDID
axe tap --label "Safari" --udid SIMULATOR_UDID
axe tap --label "Weather Alerts" --udid SIMULATOR_UDID  # Auto-uses physical touch for matched switches/toggles
axe tap --label "Submit" --tap-style simulator --udid SIMULATOR_UDID  # Force FBSimulator tapAt
axe tap -x 320 -y 780 --tap-style physical --udid SIMULATOR_UDID  # Force touch down/up for coordinates

# Tap with timing controls
axe tap -x 100 -y 200 --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID

# Swipe gestures
axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --udid SIMULATOR_UDID
axe swipe --start-x 50 --start-y 500 --end-x 350 --end-y 500 --duration 2.0 --delta 25 --udid SIMULATOR_UDID

# Raw low-level drag using explicit touch move events
axe drag --start-x 100 --start-y 400 --end-x 300 --end-y 400 --udid SIMULATOR_UDID
axe drag --start-x 100 --start-y 400 --end-x 300 --end-y 400 --duration 0.4 --steps 40 --udid SIMULATOR_UDID

# Swipe and drag with timing controls
axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID
axe drag --start-x 100 --start-y 400 --end-x 300 --end-y 400 --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID

# Advanced touch control
axe touch -x 150 -y 250 --down --udid SIMULATOR_UDID         # Touch down only
axe touch -x 150 -y 250 --up --udid SIMULATOR_UDID           # Touch up only
axe touch -x 150 -y 250 --down --up --delay 1.0 --udid SIMULATOR_UDID  # Touch with delay

3. Sliders

# Set a slider by accessibility identifier to a verified 0-100 percentage
axe slider --id slider-value-slider --value 75 --udid SIMULATOR_UDID

# Set a slider by accessibility label and narrow matching to slider elements
axe slider --label "Volume" --value 40 --element-type Slider --udid SIMULATOR_UDID

The slider command uses the slider's accessibility frame and current AXValue to perform one calibrated low-level HID drag through the same composite touch-move path as drag, then verifies the new AXValue. Since iOS slider controls quantize values to their rendered track resolution, AXe verifies that the observed value is within tolerance rather than retrying correction gestures to chase unreachable decimals. If the observed AXValue remains outside tolerance after that drag, the command fails clearly. Use describe-ui first to find reliable --id or --label selectors.

4. Gesture Presets 🆕

# Scrolling gestures
axe gesture scroll-up --udid SIMULATOR_UDID
axe gesture scroll-down --udid SIMULATOR_UDID
axe gesture scroll-left --udid SIMULATOR_UDID
axe gesture scroll-right --udid SIMULATOR_UDID

# Navigation gestures
axe gesture swipe-from-left-edge --udid SIMULATOR_UDID
axe gesture swipe-from-right-edge --udid SIMULATOR_UDID
axe gesture swipe-from-top-edge --udid SIMULATOR_UDID
axe gesture swipe-from-bottom-edge --udid SIMULATOR_UDID

# Edge swipe gestures
axe gesture swipe-from-left-edge --udid SIMULATOR_UDID
axe gesture swipe-from-bottom-edge --udid SIMULATOR_UDID

# Gesture presets with custom parameters
axe gesture scroll-up --duration 2.0 --delta 100 --udid SIMULATOR_UDID
axe gesture scroll-down --screen-width 430 --screen-height 932 --udid SIMULATOR_UDID

# Gesture presets with timing controls
axe gesture scroll-down --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID
axe gesture swipe-from-left-edge --pre-delay 2.0 --duration 0.8 --post-delay 1.0 --udid SIMULATOR_UDID

5. Hardware Buttons

# Available buttons: home, lock, side-button, siri, apple-pay
axe button home --udid SIMULATOR_UDID
axe button lock --udid SIMULATOR_UDID
axe button lock --duration 3.0 --udid SIMULATOR_UDID  # Long press

# Side button (iPhone X+)
axe button side-button --udid SIMULATOR_UDID

# Siri button
axe button siri --udid SIMULATOR_UDID

# Apple Pay button
axe button apple-pay --udid SIMULATOR_UDID

6. Keyboard Control

# Individual key presses by keycode
axe key 40 --udid SIMULATOR_UDID                    # Enter key
axe key 44 --udid SIMULATOR_UDID                    # Space key
axe key 42 --duration 1.0 --udid SIMULATOR_UDID    # Hold Backspace for 1 second

# Key sequences
axe key-sequence --keycodes 11,8,15,15,18 --udid SIMULATOR_UDID    # Type "hello"
axe key-sequence --keycodes 40,40,40 --delay 0.5 --udid SIMULATOR_UDID  # Press Enter 3 times

# Key combos (hold modifiers + press key as atomic operation)
axe key-combo --modifiers 227 --key 4 --udid SIMULATOR_UDID              # Cmd+A (Select All)
axe key-combo --modifiers 227 --key 6 --udid SIMULATOR_UDID              # Cmd+C (Copy)
axe key-combo --modifiers 227 --key 25 --udid SIMULATOR_UDID             # Cmd+V (Paste)
axe key-combo --modifiers 227,225 --key 4 --udid SIMULATOR_UDID          # Cmd+Shift+A

7. Batch Workflows

# Chain steps with one simulator/HID session
axe batch --udid SIMULATOR_UDID \
  --step "tap --id SearchField" \
  --step "type 'AXe batch input'" \
  --step "key 40"

# Add explicit per-step delay with sleep
axe batch --udid SIMULATOR_UDID \
  --step "tap -x 180 -y 360" \
  --step "sleep 0.75" \
  --step "tap -x 240 -y 420"

# Read one step per line from a file
cat > steps.txt <<'EOF'
tap --id UsernameField
type 'cam@example.com'
key 43
type 'super-secret'
key 40
EOF
axe batch --udid SIMULATOR_UDID --file steps.txt

# For large type steps, chunked mode is default; optional composite mode:
axe batch --udid SIMULATOR_UDID --type-submission composite \
  --step "type 'some long string here'"

# Toggle a setting switch by label. Automatic tap style uses physical touch for matched switches/toggles.
axe batch --udid SIMULATOR_UDID \
  --step "tap --label 'Weather Alerts'"

# Override tap style for all tap steps in a batch, or for one tap step.
axe batch --udid SIMULATOR_UDID --tap-style physical \
  --step "tap -x 320 -y 780"
axe batch --udid SIMULATOR_UDID \
  --step "tap --label 'Submit' --tap-style simulator"

Selector taps activate switch/toggle controls at the control's activation point when the matched row or label contains one switch/toggle. The default --tap-style automatic uses physical touch down/up for those switch/toggle activations and FBSimulator tapAt for normal taps.

Simple behavior rules:

One-step source only: --step, --file, or --stdin.
Steps run in order.
Default mode is fail-fast (stop at first error).
Add --continue-on-error for best-effort execution.
Keep assertions separate with describe-ui or screenshot.

For argument-by-argument behavior explanations, see BATCHING.md.

Advanced Timing Control 🆕

Pre/Post Delays

# Add delays before and after actions
axe tap -x 100 -y 200 --pre-delay 2.0 --post-delay 1.0 --udid SIMULATOR_UDID
axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --pre-delay 1.5 --udid SIMULATOR_UDID
axe gesture scroll-up --pre-delay 1.0 --post-delay 2.0 --udid SIMULATOR_UDID

Complex Timing Sequences

# Sequence with precise timing
axe tap -x 100 -y 200 --post-delay 1.0 --udid SIMULATOR_UDID
axe gesture scroll-down --pre-delay 0.5 --post-delay 1.0 --udid SIMULATOR_UDID
axe button home --udid SIMULATOR_UDID

Common Use Cases

App Navigation with Presets

# Modern app navigation using presets
axe tap -x 100 -y 200 --udid SIMULATOR_UDID                    # Launch app
axe gesture scroll-up --post-delay 1.0 --udid SIMULATOR_UDID   # Scroll content
axe gesture swipe-from-left-edge --udid SIMULATOR_UDID          # Navigate back
axe button home --udid SIMULATOR_UDID                          # Go to home screen

Pull-to-Refresh Testing

# Test scroll down functionality
axe tap -x 200 -y 400 --udid SIMULATOR_UDID                    # Tap list area
axe gesture scroll-down --pre-delay 1.0 --udid SIMULATOR_UDID  # Scroll down
axe gesture scroll-down --post-delay 2.0 --udid SIMULATOR_UDID     # Scroll to see results

Multi-Screen Testing

# Different screen sizes with presets
# iPhone 15
axe gesture scroll-up --screen-width 390 --screen-height 844 --udid SIMULATOR_UDID

# iPhone 15 Plus
axe gesture scroll-up --screen-width 430 --screen-height 932 --udid SIMULATOR_UDID

# iPad Pro
axe gesture scroll-up --screen-width 1024 --screen-height 1366 --udid SIMULATOR_UDID

Form Input with Timing

# Fill a form with proper timing
axe tap -x 150 -y 300 --post-delay 0.5 --udid SIMULATOR_UDID           # Tap text field, wait for focus
axe type 'john.doe@example.com' --udid SIMULATOR_UDID                  # Enter email
axe key 43 --udid SIMULATOR_UDID                                       # Tab to next field
axe type 'SecurePassword123!' --udid SIMULATOR_UDID                    # Enter password
axe key 40 --pre-delay 0.5 --udid SIMULATOR_UDID                      # Wait then press Enter/Submit

Gaming & Interactive Apps

# Game controls with precise timing
axe touch -x 100 -y 500 --down --udid SIMULATOR_UDID           # Start drag
axe gesture swipe-from-top-edge --pre-delay 0.2 --duration 0.3 --udid SIMULATOR_UDID  # Quick swipe action
axe touch -x 300 -y 200 --up --udid SIMULATOR_UDID             # End drag

# Edge swipes with timing
axe gesture swipe-from-left-edge --duration 0.5 --udid SIMULATOR_UDID    # Quick back
axe gesture swipe-from-right-edge --pre-delay 1.0 --duration 0.3 --udid SIMULATOR_UDID  # Forward after delay

Accessibility Testing with Presets

# Get accessibility info
axe describe-ui --point 100,200 --udid SIMULATOR_UDID

# Set a discovered slider control
axe slider --id slider-value-slider --value 75 --udid SIMULATOR_UDID

# Navigate with presets and keyboard
axe gesture scroll-down --post-delay 1.0 --udid SIMULATOR_UDID         # Scroll to content
axe key-sequence --keycodes 43,43,40 --delay 1.0 --udid SIMULATOR_UDID # Tab navigation

Video Recording

# Record to an MP4 (QuickTime compatible) in the current directory
axe record-video --udid SIMULATOR_UDID --fps 15

# Choose a custom destination
# --output automatically records using h264
axe record-video --udid SIMULATOR_UDID --fps 20 --output recordings/run.mp4

# Reduce bandwidth/size by lowering quality and scale
axe record-video --udid SIMULATOR_UDID --fps 10 --quality 55 --scale 0.6 --output recordings/light.mp4

# Simple automation-friendly script
UDID=$(axe list-simulators | awk '/Booted/{print $NF; exit}')
OUTPUT="recording_$(date +%Y%m%d_%H%M%S).mp4"

axe record-video --udid "$UDID" --fps 25 --output "$OUTPUT" &
RECORD_PID=$!

# ...run automation commands here...
axe tap -x 100 -y 200 --udid "$UDID"
axe gesture scroll-down --udid "$UDID"

sleep 2
kill -INT $RECORD_PID
wait $RECORD_PID
printf 'Saved recording to %s\n' "$OUTPUT"

Note

kill -INT sends the same signal as pressing Ctrl+C, giving AXe time to finalise the MP4 before the process exits.

Shell Escaping Solutions

❌ Problematic Examples:

# This fails due to history expansion
axe type "Hello World!" --udid SIMULATOR_UDID

# This fails due to variable expansion  
axe type "Hello $USER" --udid SIMULATOR_UDID

✅ Recommended Solutions:

1. Use Single Quotes

axe type 'Hello World!' --udid SIMULATOR_UDID
axe type 'Special chars: @#$%^&*()' --udid SIMULATOR_UDID

2. Use stdin (Best for Scripts)

echo "Hello World! Any characters work here: @#$%^&*()" | axe type --stdin --udid SIMULATOR_UDID

# In scripts
TEXT="Complex text with $variables"
echo "$TEXT" | axe type --stdin --udid SIMULATOR_UDID

3. Use Files

echo "Complex multi-line text" > input.txt
axe type --file input.txt --udid SIMULATOR_UDID

Automation Examples

Advanced Shell Script Automation

#!/bin/bash

# Get simulator UDID
UDID=$(axe list-simulators | grep "Booted" | head -1 | grep -o '[A-F0-9-]\{36\}')

# Advanced app testing with presets and timing
axe tap -x 100 -y 200 --post-delay 1.0 --udid "$UDID"           # Launch app, wait for load
axe gesture scroll-up --pre-delay 0.5 --post-delay 1.0 --udid "$UDID"  # Scroll with timing
axe gesture swipe-from-left-edge --udid "$UDID"                  # Navigate back
axe button home --pre-delay 0.5 --udid "$UDID"                  # Return home with delay

Python Script Automation with Presets

import subprocess
import time

def run_axe_command(cmd):
    subprocess.run(cmd, shell=True, check=True)

udid = "YOUR_SIMULATOR_UDID"

# Advanced interaction sequence with presets
run_axe_command(f"axe tap -x 150 -y 300 --post-delay 1.0 --udid {udid}")
run_axe_command(f"echo 'Automated input' | axe type --stdin --udid {udid}")
run_axe_command(f"axe gesture scroll-down --pre-delay 0.5 --post-delay 1.0 --udid {udid}")
run_axe_command(f"axe gesture scroll-down --udid {udid}")
run_axe_command(f"axe button home --pre-delay 1.0 --udid {udid}")

Performance Testing with Presets

# Rapid gesture testing
for gesture in scroll-up scroll-down scroll-left scroll-right; do
    axe gesture $gesture --duration 0.3 --post-delay 0.2 --udid SIMULATOR_UDID
done

# Stress testing with timing control
for i in {1..10}; do
    axe gesture swipe-from-left-edge --duration 0.4 --post-delay 0.1 --udid SIMULATOR_UDID
    axe gesture swipe-from-right-edge --duration 0.4 --post-delay 0.1 --udid SIMULATOR_UDID
done

Multi-Device Testing

# Test same gesture on different screen sizes
devices=("390,844" "430,932" "393,852" "1024,1366")
for device in "${devices[@]}"; do
    IFS=',' read -r width height <<< "$device"
    echo "Testing on ${width}x${height}"
    axe gesture scroll-up --screen-width $width --screen-height $height --udid SIMULATOR_UDID
    axe gesture scroll-down --screen-width $width --screen-height $height --udid SIMULATOR_UDID
done

Gesture Preset Reference 🆕

Available Presets

Preset	Description	Default Duration	Default Delta	Use Case
`scroll-up`	Scroll up in center	0.5s	25px	Content scrolling
`scroll-down`	Scroll down in center	0.5s	25px	Content scrolling
`scroll-left`	Scroll left in center	0.5s	25px	Horizontal scrolling
`scroll-right`	Scroll right in center	0.5s	25px	Horizontal scrolling
`swipe-from-left-edge`	Left edge to right	0.3s	50px	Back navigation
`swipe-from-right-edge`	Right edge to left	0.3s	50px	Forward navigation
`swipe-from-top-edge`	Top to bottom	0.3s	50px	Dismiss/close
`swipe-from-bottom-edge`	Bottom to top	0.3s	50px	Open/reveal

Timing Control Reference 🆕

Parameter	Range	Description	Available On
`--pre-delay`	0-10 seconds	Delay before action	tap, swipe, drag, gesture
`--post-delay`	0-10 seconds	Delay after action	tap, swipe, drag, gesture
`--duration`	0-10 seconds	Action duration	swipe, drag, gesture, button, key
`--steps`	1-1000	Touch move event count	drag
`--delay`	0-5 seconds	Between-key delay	key-sequence, touch

Benchmarking Batch vs Non-Batch

# Build AXe binary
swift build

# Run benchmark on a booted simulator
scripts/benchmark_batch.sh --udid SIMULATOR_UDID --iterations 20 --rounds 5

This benchmark compares equivalent two-tap workflows and reports per-iteration latency plus speedup.

Key Advantages

Complete HID Coverage: All idb functionality now available in AXe
Gesture Presets: 11 common patterns with intelligent defaults
Precise Timing Control: Pre/post delays for complex automation
Multi-Screen Support: Automatic coordinate calculation for different devices
No Shell Escaping: Use --stdin or --file for complex text
Automation-Friendly: Perfect for CI/CD and testing scripts
Flexible Input Methods: Multiple ways to provide input and control timing
Slider Verification: Slider controls use selector-resolved low-level HID dragging with AXValue tolerance verification
Comprehensive Validation: Built-in parameter validation and error handling

Common Keycodes Reference

# Letters (lowercase)
a=4, b=5, c=6, d=7, e=8, f=9, g=10, h=11, i=12, j=13, k=14, l=15, m=16
n=17, o=18, p=19, q=20, r=21, s=22, t=23, u=24, v=25, w=26, x=27, y=28, z=29

# Numbers
1=30, 2=31, 3=32, 4=33, 5=34, 6=35, 7=36, 8=37, 9=38, 0=39

# Special keys
Enter=40, Escape=41, Backspace=42, Tab=43, Space=44
Minus=45, Equal=46, LeftBracket=47, RightBracket=48, Backslash=49
Semicolon=51, Quote=52, Grave=53, Comma=54, Period=55, Slash=56

# Function keys
F1=58, F2=59, F3=60, F4=61, F5=62, F6=63, F7=64, F8=65, F9=66, F10=67

# Modifier keys
LeftCtrl=224, LeftShift=225, LeftAlt=226, LeftGUI=227
RightCtrl=228, RightShift=229, RightAlt=230, RightGUI=231

Uh oh!

FilesExpand file tree

USAGE_EXAMPLES.md

Latest commit

History