AXe iOS 模拟器 UI 自动化 CLI 工具：基于辅助功能 API 的稳定测试

axiom-axe-ref by charleswiltgen/axiom

131 周安装量

678 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-axe-ref

iOS 自动化测试

🇨🇳中文介绍

AXe 参考文档 (iOS 模拟器 UI 自动化)

AXe 是一个使用 Apple 辅助功能 API 和 HID 功能与 iOS 模拟器交互的 CLI 工具。单一二进制文件，无需守护进程。

安装

brew install cameroncooke/axe/axe

# 验证安装
axe --version

关键最佳实践：首先使用 describe_ui

在进行 UI 交互之前，务必先运行 describe_ui。 切勿通过截图猜测坐标。

最佳实践： 在使用 x/y 参数之前，使用 describe-ui 获取精确的元素坐标（不要通过截图猜测）。

# 1. 第一步：获取带有框架坐标的 UI 树
axe describe-ui --udid $UDID

# 2. 然后：通过辅助功能 ID 点击（首选）
axe tap --id "loginButton" --udid $UDID

# 3. 或者：通过标签点击
axe tap --label "Login" --udid $UDID

# 4. 最后手段：使用 describe-ui 输出的坐标点击
axe tap -x 200 -y 400 --udid $UDID

定位元素的优先级顺序：

--id (accessibilityIdentifier) - 最稳定
--label (辅助功能标签) - 稳定，但可能因本地化而改变

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

核心理念：辅助功能优先

AXe 的关键优势：通过辅助功能标识符或标签点击元素，而不仅仅是坐标。

# 基于坐标（脆弱 - 布局改变时会失效）
axe tap -x 200 -y 400 --udid $UDID

# 基于辅助功能（稳定 - 可承受 UI 变化）
axe tap --id "loginButton" --udid $UDID
axe tap --label "Login" --udid $UDID

始终优先使用 --id 或 --label 而非坐标。

获取模拟器 UDID

AXe 大多数命令需要模拟器 UDID：

# 获取已启动模拟器的 UDID
UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)

# 列出所有模拟器
axe list-simulators

触摸与点击命令

通过辅助功能标识符点击（推荐）

# 点击具有 accessibilityIdentifier 的元素
axe tap --id "loginButton" --udid $UDID

# 点击具有辅助功能标签的元素
axe tap --label "Submit" --udid $UDID

# 基本点击
axe tap -x 200 -y 400 --udid $UDID

# 带定时控制的点击
axe tap -x 200 -y 400 --pre-delay 0.5 --post-delay 0.3 --udid $UDID

# 长按（按住持续时间，单位秒）
axe tap -x 200 -y 400 --duration 1.0 --udid $UDID

# 触摸按下（手指按下）
axe touch down -x 200 -y 400 --udid $UDID

# 触摸抬起（手指释放）
axe touch up -x 200 -y 400 --udid $UDID

滑动与手势命令

# 从点 A 滑动到点 B
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --udid $UDID

# 带持续时间的滑动（越慢越明显）
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --duration 0.5 --udid $UDID

# 滚动
axe gesture scroll-up --udid $UDID      # 向上滚动内容（向下滑动）
axe gesture scroll-down --udid $UDID    # 向下滚动内容（向上滑动）
axe gesture scroll-left --udid $UDID
axe gesture scroll-right --udid $UDID

# 边缘滑动（导航）
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 # 主屏幕指示器/控制中心

# 输入文本（元素必须已聚焦）
axe type "user@example.com" --udid $UDID

# 字符间带延迟地输入文本
axe type "password123" --char-delay 0.1 --udid $UDID

# 从标准输入输入
echo "Hello World" | axe type --stdin --udid $UDID

# 从文件输入
axe type --file /tmp/input.txt --udid $UDID

# 通过 HID 键码按下特定键
axe key 40 --udid $UDID  # Return/Enter

# 常用键码：
# 40 = Return/Enter
# 41 = Escape
# 42 = Backspace/Delete
# 43 = Tab
# 44 = Space
# 79 = 右箭头
# 80 = 左箭头
# 81 = 下箭头
# 82 = 上箭头

# 带定时的按键序列
axe key-sequence 40 43 40 --delay 0.2 --udid $UDID

# 主屏幕按钮
axe button home --udid $UDID

# 锁定/电源按钮
axe button lock --udid $UDID

# 长按电源键（关机对话框）
axe button lock --duration 3.0 --udid $UDID

# 侧边按钮 (iPhone X+)
axe button side-button --udid $UDID

# Siri
axe button siri --udid $UDID

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

# 截图到自动命名的文件
axe screenshot --udid $UDID
# 输出：screenshot_2026-01-11_143052.png

# 截图到指定文件
axe screenshot --output /tmp/my-screenshot.png --udid $UDID

# 截图到标准输出（用于管道）
axe screenshot --stdout --udid $UDID > screenshot.png

视频录制与流传输

# 开始录制（按 Ctrl+C 停止）
axe record-video --output /tmp/recording.mp4 --udid $UDID

# 带质量设置的录制
axe record-video --output /tmp/recording.mp4 --quality high --udid $UDID

# 带缩放比例的录制（减小文件大小）
axe record-video --output /tmp/recording.mp4 --scale 0.5 --udid $UDID

# 以 10 FPS 流传输（默认）
axe stream-video --udid $UDID

# 以特定帧率流传输 (1-30 FPS)
axe stream-video --fps 30 --udid $UDID

# 流传输格式
axe stream-video --format mjpeg --udid $UDID   # MJPEG（默认）
axe stream-video --format jpeg --udid $UDID    # 单独的 JPEG
axe stream-video --format ffmpeg --udid $UDID  # FFmpeg 兼容
axe stream-video --format bgra --udid $UDID    # 原始 BGRA

UI 检查 (describe-ui)

对于查找辅助功能标识符和标签至关重要。

# 获取完整的辅助功能树
axe describe-ui --udid $UDID

# 输出包括：
# - 元素类型 (Button, TextField, StaticText 等)
# - 辅助功能标识符
# - 辅助功能标签
# - 框架（位置和大小）
# - 启用/禁用状态

# 获取特定坐标处的元素
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)

# 点击邮箱字段并输入
axe tap --id "emailTextField" --udid $UDID
axe type "user@example.com" --udid $UDID

# 点击密码字段并输入
axe tap --id "passwordTextField" --udid $UDID
axe type "password123" --udid $UDID

# 点击登录按钮
axe tap --id "loginButton" --udid $UDID

# 等待并截图
sleep 2
axe screenshot --output /tmp/login-result.png --udid $UDID

自动化前发现元素

# 1. 获取 UI 树
axe describe-ui --udid $UDID > /tmp/ui-tree.json

# 2. 查找元素（搜索标识符）
cat /tmp/ui-tree.json | jq '.[] | select(.identifier != null) | {identifier, label, type}'

# 3. 在自动化中使用发现的标识符
axe tap --id "discoveredIdentifier" --udid $UDID

# 向下滚动直到元素出现（伪代码模式）
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

# 带错误捕获的自动化
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`	字符间延迟（用于输入）

# 带完整定时控制的示例
axe tap --id "button" --pre-delay 0.5 --post-delay 0.3 --udid $UDID

AXe 与 simctl 对比

功能	simctl	AXe
设备生命周期	✅	❌
权限	✅	❌
推送通知	✅	❌
状态栏	✅	❌
深度链接	✅	❌
截图	✅	✅ (PNG)
视频录制	✅	✅ (H.264)
视频流传输	❌	✅
UI 点击/滑动	❌	✅
输入文本	❌	✅
硬件按钮	❌	✅
辅助功能树	❌	✅

两者结合使用：simctl 用于设备控制，AXe 用于 UI 自动化。

运行 axe describe-ui 查看可用元素
检查元素在代码中是否设置了 accessibilityIdentifier
确保元素可见（不在屏幕外）

检查元素是否启用（describe-ui 中 "enabled": true）
对于加载缓慢的 UI，尝试添加 --pre-delay 0.5
使用 axe list-simulators 验证正确的 UDID

确保文本字段首先获得焦点：axe tap --id "textField"
检查键盘是否可见
尝试 --char-delay 0.05 以提高可靠性

AXe 使用私有 API - 确保您在安装了 Xcode 的 Mac 上运行，并具有适当的权限。

🇺🇸English

AXe Reference (iOS Simulator UI Automation)

AXe is a CLI tool for interacting with iOS Simulators using Apple's Accessibility APIs and HID functionality. Single binary, no daemon required.

Installation

brew install cameroncooke/axe/axe

# Verify installation
axe --version

Critical Best Practice: describe_ui First

ALWAYS rundescribe_ui before UI interactions. Never guess coordinates from screenshots.

Best practice: Use describe-ui to get precise element coordinates prior to using x/y parameters (don't guess from screenshots).

# 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

Priority order for targeting elements:

--id (accessibilityIdentifier) - most stable
--label (accessibility label) - stable but may change with localization
-x -y coordinates from describe-ui - fragile, use only when no identifier

Core Concept: Accessibility-First

AXe's key advantage : Tap elements by accessibility identifier or label, not just coordinates.

# 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

Always prefer--id or --label over coordinates.

Getting the Simulator UDID

AXe requires the simulator UDID for most commands:

# 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

Touch & Tap Commands

Tap by Accessibility Identifier (Recommended)

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

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

Tap by Coordinates

# 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

Low-Level Touch Events

# 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 & Gesture Commands

Custom Swipe

# 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

Gesture Presets

# 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

Text Input

Type Text

# Type text (element must be focused)
axe type "user@example.com" --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

Keyboard Keys

# 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

Hardware Buttons

# 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

Screenshots

# 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

Video Recording & Streaming

Record Video

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

# 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 Inspection (describe-ui)

Critical for finding accessibility identifiers and labels.

Full Screen UI Tree

# 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

Point-Specific UI Info

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

Example Output

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

Common Workflows

Login Flow

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 "user@example.com" --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

Discover Elements Before Automating

# 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 to Find Element

# 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

Screenshot on Error

# 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

Timing Controls

Most commands support timing options:

Option	Description
`--pre-delay`	Wait before action (seconds)
`--post-delay`	Wait after action (seconds)
`--duration`	Action duration (for taps, button presses)
`--char-delay`	Delay between characters (for type)

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

AXe vs simctl

Capability	simctl	AXe
Device lifecycle	✅	❌
Permissions	✅	❌
Push notifications	✅	❌
Status bar	✅	❌
Deep links	✅	❌
Screenshots	✅	✅ (PNG)
Video recording	✅	✅ (H.264)
Video streaming	❌	✅
UI tap/swipe	❌	✅
Type text	❌	✅
Hardware buttons

Use both together : simctl for device control, AXe for UI automation.

Troubleshooting

Element Not Found

Run axe describe-ui to see available elements
Check element has accessibilityIdentifier set in code
Ensure element is visible (not off-screen)

Tap Doesn't Work

Check element is enabled ("enabled": true in describe-ui)
Try adding --pre-delay 0.5 for slow-loading UI
Verify correct UDID with axe list-simulators

Type Not Working

Ensure text field is focused first: axe tap --id "textField"
Check keyboard is visible
Try --char-delay 0.05 for reliability

Permission Denied

AXe uses private APIs - ensure you're running on a Mac with Xcode installed and proper entitlements.

Resources

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

Related : xcsentinel (build orchestration)

Skills : axiom-xctest-automation, axiom-ui-testing

Agents : simulator-tester, test-runner

Weekly Installs

Repository

charleswiltgen/axiom

GitHub Stars

601

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

opencode77

claude-code71

codex71

gemini-cli70

cursor69

github-copilot67

通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南

36,300 周安装

AXe iOS 模拟器 UI 自动化 CLI 工具：基于辅助功能 API 的稳定测试

🇨🇳中文介绍

AXe 参考文档 (iOS 模拟器 UI 自动化)

安装

关键最佳实践：首先使用 describe_ui

相关 Skills

核心理念：辅助功能优先

获取模拟器 UDID

触摸与点击命令

通过辅助功能标识符点击（推荐）

通过坐标点击

底层触摸事件

滑动与手势命令

自定义滑动

手势预设

文本输入

输入文本

键盘按键

硬件按钮

截图