iOS App Tester (AXe CLI)

Overview

Test and automate iOS Simulator applications using AXe, a command-line tool that leverages Apple's Accessibility APIs for programmatic simulator control. AXe runs as a single binary with no server setup required.

When to Use

Automating iOS Simulator UI interactions for testing
Auditing accessibility labels and VoiceOver descriptions
Recording test execution videos
Scripting repeatable test scenarios
CI/CD pipeline iOS testing integration

Prerequisites

macOS with Xcode installed
iOS Simulator (included with Xcode)
Homebrew (for installation)

Installation

brew tap cameroncooke/axe
brew install axe

Verify installation:

axe --help

Quick Start

Find your simulator UDID:

axe list-simulators

Tap a coordinate:

axe tap -x 200 -y 400 --udid <SIMULATOR_UDID>

Inspect accessibility elements:

axe describe-ui --udid <SIMULATOR_UDID>

Command Reference

Simulator Discovery

# List all available simulators with UDIDs
axe list-simulators

Touch Interactions

# Tap at coordinates
axe tap -x 100 -y 200 --udid <UDID>

# Swipe gesture
axe swipe --start-x 100 --start-y 500 --end-x 100 --end-y 200 --udid <UDID>

# Low-level touch events
axe touch-down -x 100 -y 200 --udid <UDID>
axe touch-up -x 100 -y 200 --udid <UDID>

Preset Gestures

# Scrolling
axe gesture scroll-up --udid <UDID>
axe gesture scroll-down --udid <UDID>
axe gesture scroll-left --udid <UDID>
axe gesture scroll-right --udid <UDID>

# Edge swipes (for navigation)
axe gesture swipe-from-left-edge --udid <UDID>
axe gesture swipe-from-right-edge --udid <UDID>
axe gesture swipe-from-top-edge --udid <UDID>
axe gesture swipe-from-bottom-edge --udid <UDID>

Text Input

# Type text directly
axe type 'Hello World!' --udid <UDID>

# Type from stdin (useful for passwords/sensitive data)
echo "secret" | axe type --stdin --udid <UDID>

# Type from file
axe type --file input.txt --udid <UDID>

Hardware Buttons

# Home button
axe button home --udid <UDID>

# Lock/power button
axe button lock --udid <UDID>

# Long press (e.g., for Siri)
axe button lock --duration 2.0 --udid <UDID>

# Side button
axe button side --udid <UDID>

# Apple Pay
axe button apple-pay --udid <UDID>

Accessibility Inspection

# Describe all UI elements (full screen)
axe describe-ui --udid <UDID>

# Describe element at specific point
axe describe-ui --point 100,200 --udid <UDID>

Video Recording

# Record to MP4 file
axe record-video --udid <UDID> --fps 15 --output test-recording.mp4

# Stream video (for ffmpeg piping)
axe stream-video --udid <UDID> --fps 30 --format ffmpeg | ffmpeg -i - output.mp4

# Stream as MJPEG
axe stream-video --udid <UDID> --fps 10 --format mjpeg > stream.mjpeg

Timing Control

All commands support delays for sequencing:

# Wait before action
axe tap -x 100 -y 200 --pre-delay 1.0 --udid <UDID>

# Wait after action
axe tap -x 100 -y 200 --post-delay 0.5 --udid <UDID>

# Combined delays
axe type 'text' --pre-delay 0.5 --post-delay 1.0 --udid <UDID>

Accessibility Testing Workflow

1. Audit Full Screen

# Get all accessibility elements
axe describe-ui --udid <UDID> > accessibility-audit.txt

Review output for:

Missing accessibilityLabel values
Generic labels like "button" or "image"
Missing accessibilityHint for complex actions
Incorrect accessibilityTraits

2. Point-Based Inspection

# Check specific element
axe describe-ui --point 200,400 --udid <UDID>

3. VoiceOver Simulation Script

#!/bin/bash
UDID="YOUR_SIMULATOR_UDID"

# Navigate through app elements
axe gesture swipe-from-left-edge --udid $UDID --post-delay 1.0
axe describe-ui --udid $UDID

axe tap -x 200 -y 400 --udid $UDID --post-delay 0.5
axe describe-ui --udid $UDID

Automation Example

#!/bin/bash
UDID="YOUR_SIMULATOR_UDID"

# Login flow automation
echo "Starting login test..."

# Tap email field
axe tap -x 200 -y 300 --udid $UDID --post-delay 0.3

# Type email
axe type 'test@example.com' --udid $UDID --post-delay 0.3

# Tap password field
axe tap -x 200 -y 380 --udid $UDID --post-delay 0.3

# Type password (from stdin for security)
echo "password123" | axe type --stdin --udid $UDID --post-delay 0.3

# Tap login button
axe tap -x 200 -y 480 --udid $UDID --post-delay 2.0

# Verify result - check for expected element
axe describe-ui --udid $UDID | grep -q "Welcome" && echo "Login successful"

CI/CD Integration

# GitHub Actions example
- name: Run iOS UI Tests
  run: |
    # Boot simulator
    xcrun simctl boot "iPhone 15"
    UDID=$(xcrun simctl list devices | grep "iPhone 15" | grep -oE '[A-F0-9-]{36}')

    # Install app
    xcrun simctl install $UDID ./build/MyApp.app
    xcrun simctl launch $UDID com.example.myapp

    # Run AXe tests
    axe describe-ui --udid $UDID > accessibility-report.txt

    # Record test
    axe record-video --udid $UDID --fps 10 --output test.mp4 &
    VIDEO_PID=$!

    # Run automation script
    ./test-scripts/login-flow.sh $UDID

    kill $VIDEO_PID

Troubleshooting

"Simulator not found"

# Ensure simulator is booted
xcrun simctl boot "iPhone 15"

# Get correct UDID
axe list-simulators

"Permission denied"

# Grant accessibility permissions in System Preferences
# Security & Privacy > Privacy > Accessibility

Commands not responding

# Ensure app is in foreground
xcrun simctl launch <UDID> <BUNDLE_ID>

# Add delays between commands
axe tap -x 100 -y 200 --post-delay 1.0 --udid <UDID>

Best Practices

Always use --post-delay between commands for reliability
Store UDID in environment variable for scripts
Use describe-ui before and after actions to verify state
Record video during test runs for debugging
Pipe sensitive text through stdin, not command line args
Run accessibility audits as part of CI/CD pipeline

ios-app-tester