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

# 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

# Swipe 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

# 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. 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

4. 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

5. 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

6. 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'"

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

# 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, gesture
`--post-delay`	0-10 seconds	Delay after action	tap, swipe, gesture
`--duration`	0-10 seconds	Action duration	swipe, gesture, button, key
`--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
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