ckorhonen/ios-app-tester

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

1. Find your simulator UDID:

axe list-simulators

2. Tap a coordinate:

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

3. 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 '[email protected]' --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