axiom-axe-ref

AXe リファレンス（iOS Simulator UI オートメーション）

AXe は、Apple のアクセシビリティ API と HID 機能を使用して iOS Simulator を操作する CLI ツールです。単一のバイナリで、デーモンは不要です。

インストール

brew install cameroncooke/axe/axe

# Verify installation
axe --version

重要なベストプラクティス：最初に describe_ui を実行

UI を操作する前に、必ず describe_ui を実行してください。 スクリーンショットから座標を推測してはいけません。

ベストプラクティス： x/y パラメーターを使用する前に describe-ui を使って正確な要素の座標を取得してください（スクリーンショットから推測しないでください）。

# 1. FIRST: Get the UI tree with frame coordinates
axe describe-ui --udid $UDID

# 2. THEN: Tap by accessibility ID (preferred)
axe tap --id "loginButton" --udid $UDID

# 3. OR: Tap by label
axe tap --label "Login" --udid $UDID

# 4. LAST RESORT: Tap by coordinates from describe-ui output
axe tap -x 200 -y 400 --udid $UDID

要素を指定する際の優先順位：

1. --id（accessibilityIdentifier）— 最も安定しています
2. --label（アクセシビリティラベル）— 安定していますが、ローカライズによって変わる場合があります
3. describe-ui で取得した -x -y 座標 — 不安定なため、識別子がない場合にのみ使用してください

基本概念：アクセシビリティ優先

AXe の主な利点： 座標だけでなく、アクセシビリティ識別子またはラベルで要素をタップできます。

# Coordinate-based (fragile - breaks with layout changes)
axe tap -x 200 -y 400 --udid $UDID

# Accessibility-based (stable - survives UI changes)
axe tap --id "loginButton" --udid $UDID
axe tap --label "Login" --udid $UDID

座標よりも、常に --id または --label を優先してください。

Simulator の UDID を取得する

AXe では、ほとんどのコマンドで Simulator の UDID が必要です。

# Get booted simulator UDID
UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)

# List all simulators
axe list-simulators

タッチとタップのコマンド

アクセシビリティ識別子でタップ（推奨）

# Tap element with accessibilityIdentifier
axe tap --id "loginButton" --udid $UDID

# Tap element with accessibility label
axe tap --label "Submit" --udid $UDID

座標でタップ

# Basic tap
axe tap -x 200 -y 400 --udid $UDID

# Tap with timing controls
axe tap -x 200 -y 400 --pre-delay 0.5 --post-delay 0.3 --udid $UDID

# Long press (hold duration in seconds)
axe tap -x 200 -y 400 --duration 1.0 --udid $UDID

低レベルのタッチイベント

# Touch down (finger press)
axe touch down -x 200 -y 400 --udid $UDID

# Touch up (finger release)
axe touch up -x 200 -y 400 --udid $UDID

スワイプとジェスチャーのコマンド

カスタムスワイプ

# Swipe from point A to point B
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --udid $UDID

# Swipe with duration (slower = more visible)
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --duration 0.5 --udid $UDID

ジェスチャーのプリセット

# Scrolling
axe gesture scroll-up --udid $UDID      # Scroll content up (swipe down)
axe gesture scroll-down --udid $UDID    # Scroll content down (swipe up)
axe gesture scroll-left --udid $UDID
axe gesture scroll-right --udid $UDID

# Edge swipes (navigation)
axe gesture swipe-from-left-edge --udid $UDID   # Back navigation
axe gesture swipe-from-right-edge --udid $UDID
axe gesture swipe-from-top-edge --udid $UDID    # Notification Center
axe gesture swipe-from-bottom-edge --udid $UDID # Home indicator/Control Center

テキスト入力

テキストを入力

# Type text (element must be focused)
axe type "[email protected]" --udid $UDID

# Type with delay between characters
axe type "password123" --char-delay 0.1 --udid $UDID

# Type from stdin
echo "Hello World" | axe type --stdin --udid $UDID

# Type from file
axe type --file /tmp/input.txt --udid $UDID

キーボードキー

# Press specific key by HID keycode
axe key 40 --udid $UDID  # Return/Enter

# Common keycodes:
# 40 = Return/Enter
# 41 = Escape
# 42 = Backspace/Delete
# 43 = Tab
# 44 = Space
# 79 = Right Arrow
# 80 = Left Arrow
# 81 = Down Arrow
# 82 = Up Arrow

# Key sequence with timing
axe key-sequence 40 43 40 --delay 0.2 --udid $UDID

ハードウェアボタン

# Home button
axe button home --udid $UDID

# Lock/Power button
axe button lock --udid $UDID

# Long press power (shutdown dialog)
axe button lock --duration 3.0 --udid $UDID

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

# Siri
axe button siri --udid $UDID

# Apple Pay
axe button apple-pay --udid $UDID

スクリーンショット

# Screenshot to auto-named file
axe screenshot --udid $UDID
# Output: screenshot_2026-01-11_143052.png

# Screenshot to specific file
axe screenshot --output /tmp/my-screenshot.png --udid $UDID

# Screenshot to stdout (for piping)
axe screenshot --stdout --udid $UDID > screenshot.png

ビデオ録画とストリーミング

ビデオを録画

# Start recording (Ctrl+C to stop)
axe record-video --output /tmp/recording.mp4 --udid $UDID

# Record with quality settings
axe record-video --output /tmp/recording.mp4 --quality high --udid $UDID

# Record with scale (reduce file size)
axe record-video --output /tmp/recording.mp4 --scale 0.5 --udid $UDID

ビデオをストリーミング

# Stream at 10 FPS (default)
axe stream-video --udid $UDID

# Stream at specific framerate (1-30 FPS)
axe stream-video --fps 30 --udid $UDID

# Stream formats
axe stream-video --format mjpeg --udid $UDID   # MJPEG (default)
axe stream-video --format jpeg --udid $UDID    # Individual JPEGs
axe stream-video --format ffmpeg --udid $UDID  # FFmpeg compatible
axe stream-video --format bgra --udid $UDID    # Raw BGRA

UI の検査（describe-ui）

アクセシビリティ識別子とラベルを見つけるうえで重要です。

全画面の UI ツリー

# Get complete accessibility tree
axe describe-ui --udid $UDID

# Output includes:
# - Element type (Button, TextField, StaticText, etc.)
# - Accessibility identifier
# - Accessibility label
# - Frame (position and size)
# - Enabled/disabled state

特定のポイントの UI 情報

# Get element at specific coordinates
axe describe-ui --point 200,400 --udid $UDID

出力例

{
  "type": "Button",
  "identifier": "loginButton",
  "label": "Login",
  "frame": {"x": 150, "y": 380, "width": 100, "height": 44},
  "enabled": true,
  "focused": false
}

一般的なワークフロー

ログインフロー

UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)

# Tap email field and type
axe tap --id "emailTextField" --udid $UDID
axe type "[email protected]" --udid $UDID

# Tap password field and type
axe tap --id "passwordTextField" --udid $UDID
axe type "password123" --udid $UDID

# Tap login button
axe tap --id "loginButton" --udid $UDID

# Wait and screenshot
sleep 2
axe screenshot --output /tmp/login-result.png --udid $UDID

自動化の前に要素を確認

# 1. Get the UI tree
axe describe-ui --udid $UDID > /tmp/ui-tree.json

# 2. Find elements (search for identifiers)
cat /tmp/ui-tree.json | jq '.[] | select(.identifier != null) | {identifier, label, type}'

# 3. Use discovered identifiers in automation
axe tap --id "discoveredIdentifier" --udid $UDID

要素が見つかるまでスクロール

# Scroll down until element appears (pseudo-code pattern)
for i in {1..5}; do
  if axe describe-ui --udid $UDID | grep -q "targetElement"; then
    axe tap --id "targetElement" --udid $UDID
    break
  fi
  axe gesture scroll-down --udid $UDID
  sleep 0.5
done

エラー発生時にスクリーンショットを撮影

# Automation with error capture
if ! axe tap --id "submitButton" --udid $UDID; then
  axe screenshot --output /tmp/error-state.png --udid $UDID
  axe describe-ui --udid $UDID > /tmp/error-ui-tree.json
  echo "Failed to tap submitButton - see error-state.png"
fi

タイミングの制御

ほとんどのコマンドはタイミングオプションに対応しています。

オプション	説明
--pre-delay	操作の前に待機（秒）
--post-delay	操作の後に待機（秒）
--duration	操作の継続時間（タップ、ボタン押下の場合）
--char-delay	文字間の遅延（入力の場合）

# Example with full timing control
axe tap --id "button" --pre-delay 0.5 --post-delay 0.3 --udid $UDID

AXe と simctl の比較

機能	simctl	AXe
デバイスのライフサイクル	✅	❌
権限	✅	❌
プッシュ通知	✅	❌
ステータスバー	✅	❌
ディープリンク	✅	❌
スクリーンショット	✅	✅（PNG）
ビデオ録画	✅	✅（H.264）
ビデオストリーミング	❌	✅
UI のタップ／スワイプ	❌	✅
テキスト入力	❌	✅
ハードウェアボタン	❌	✅
アクセシビリティツリー	❌	✅

両方を併用してください：デバイスの制御には simctl、UI オートメーションには AXe を使用します。

トラブルシューティング

要素が見つからない

1. axe describe-ui を実行して、利用可能な要素を確認します
2. コードで要素に accessibilityIdentifier が設定されていることを確認します
3. 要素が表示されていること（画面外にないこと）を確認します

タップが機能しない

1. 要素が有効になっていることを確認します（describe-ui で "enabled": true）
2. UI の読み込みが遅い場合は、--pre-delay 0.5 を追加してみます
3. axe list-simulators で正しい UDID を確認します

入力が機能しない

1. 最初にテキストフィールドにフォーカスがあることを確認します：axe tap --id "textField"
2. キーボードが表示されていることを確認します
3. 確実に入力するため、--char-delay 0.05 を試します

権限が拒否される

AXe はプライベート API を使用します。Xcode がインストールされ、適切なエンタイトルメントが設定された Mac で実行してください。

リソース

GitHub：https://github.com/cameroncooke/AXe

関連ツール：xcsentinel（ビルドオーケストレーション）

スキル：axiom-xctest-automation、axiom-ui-testing

エージェント：simulator-tester、test-runner