Back to Details

axiom-axe-ref

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AXe Reference (iOS Simulator UI Automation)

AXe 使用参考（iOS Simulator UI自动化）

AXe is a CLI tool for interacting with iOS Simulators using Apple's Accessibility APIs and HID functionality. Single binary, no daemon required.
AXe是一款CLI工具，通过Apple的无障碍API和HID功能与iOS Simulator进行交互。它是单一二进制文件，无需运行守护进程。

Installation

安装

bash
brew install cameroncooke/axe/axe
bash
brew install cameroncooke/axe/axe

Verify installation

Verify installation

axe --version
undefined
axe --version
undefined

Critical Best Practice: describe_ui First

关键最佳实践：先执行describe_ui

ALWAYS run 
describe_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).
bash
undefined
在进行UI交互前，务必先运行
describe_ui
。永远不要通过截图猜测坐标。
最佳实践： 使用describe-ui获取精确的元素坐标后，再使用x/y参数（不要通过截图猜测）。
bash
undefined

1. FIRST: Get the UI tree with frame coordinates

1. 第一步：获取包含框架坐标的UI树

axe describe-ui --udid $UDID
axe describe-ui --udid $UDID

2. THEN: Tap by accessibility ID (preferred)

2. 第二步：通过无障碍ID点击（推荐方式）

axe tap --id "loginButton" --udid $UDID
axe tap --id "loginButton" --udid $UDID

3. OR: Tap by label

3. 或者：通过标签点击

axe tap --label "Login" --udid $UDID
axe tap --label "Login" --udid $UDID

4. LAST RESORT: Tap by coordinates from describe-ui output

4. 最后手段：通过describe-ui输出的坐标点击

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

**Priority order for targeting elements:**
1. `--id` (accessibilityIdentifier) - most stable
2. `--label` (accessibility label) - stable but may change with localization
3. `-x -y` coordinates from `describe-ui` - fragile, use only when no identifier
axe tap -x 200 -y 400 --udid $UDID

**定位元素的优先级顺序：**
1. `--id`（accessibilityIdentifier）- 最稳定
2. `--label`（无障碍标签）- 稳定但可能随本地化变更
3. 来自`describe-ui`的`-x -y`坐标 - 易受影响，仅在没有标识符时使用

Core Concept: Accessibility-First

核心概念：优先使用无障碍功能

AXe's key advantage: Tap elements by accessibility identifier or label, not just coordinates.
bash
undefined
AXe的主要优势：通过无障碍标识符或标签点击元素，而不仅仅是坐标。
bash
undefined

Coordinate-based (fragile - breaks with layout changes)

基于坐标的方式（易受影响 - 布局变更时会失效）

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

Accessibility-based (stable - survives UI changes)

基于无障碍功能的方式（稳定 - 可承受UI变更）

axe tap --id "loginButton" --udid $UDID axe tap --label "Login" --udid $UDID

**Always prefer `--id` or `--label` over coordinates.**
axe tap --id "loginButton" --udid $UDID axe tap --label "Login" --udid $UDID

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

Getting the Simulator UDID

获取Simulator UDID

AXe requires the simulator UDID for most commands:
bash
undefined
AXe的大多数命令需要模拟器UDID：
bash
undefined

Get booted simulator UDID

获取已启动模拟器的UDID

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

List all simulators

列出所有模拟器

axe list-simulators
undefined
axe list-simulators
undefined

Touch & Tap Commands

触摸与点击命令

Tap by Accessibility Identifier (Recommended)

通过无障碍ID点击（推荐）

bash
undefined
bash
undefined

Tap element with accessibilityIdentifier

点击带有accessibilityIdentifier的元素

axe tap --id "loginButton" --udid $UDID
axe tap --id "loginButton" --udid $UDID

Tap element with accessibility label

点击带有无障碍标签的元素

axe tap --label "Submit" --udid $UDID
undefined
axe tap --label "Submit" --udid $UDID
undefined

Tap by Coordinates

通过坐标点击

bash
undefined
bash
undefined

Basic tap

基础点击

axe tap -x 200 -y 400 --udid $UDID
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
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
undefined
axe tap -x 200 -y 400 --duration 1.0 --udid $UDID
undefined

Low-Level Touch Events

底层触摸事件

bash
undefined
bash
undefined

Touch down (finger press)

按下触摸（手指按下）

axe touch down -x 200 -y 400 --udid $UDID
axe touch down -x 200 -y 400 --udid $UDID

Touch up (finger release)

抬起触摸（手指松开）

axe touch up -x 200 -y 400 --udid $UDID
undefined
axe touch up -x 200 -y 400 --udid $UDID
undefined

Swipe & Gesture Commands

滑动与手势命令

Custom Swipe

自定义滑动

bash
undefined
bash
undefined

Swipe from point A to point B

从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 --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
undefined
axe swipe --start-x 200 --start-y 600 --end-x 200 --end-y 200 --duration 0.5 --udid $UDID
undefined

Gesture Presets

预设手势

bash
undefined
bash
undefined

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
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 (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
undefined
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 # 主屏幕指示器/控制中心
undefined

Text Input

文本输入

Type Text

输入文本

bash
undefined
bash
undefined

Type text (element must be focused)

输入文本（元素必须已获得焦点）

axe type "user@example.com" --udid $UDID
axe type "user@example.com" --udid $UDID

Type with delay between characters

带字符间延迟的输入

axe type "password123" --char-delay 0.1 --udid $UDID
axe type "password123" --char-delay 0.1 --udid $UDID

Type from stdin

从标准输入读取并输入

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

Type from file

从文件读取并输入

axe type --file /tmp/input.txt --udid $UDID
undefined
axe type --file /tmp/input.txt --udid $UDID
undefined

Keyboard Keys

键盘按键

bash
undefined
bash
undefined

Press specific key by HID keycode

通过HID键码按下特定按键

axe key 40 --udid $UDID # Return/Enter
axe key 40 --udid $UDID # 回车键/换行键

Common keycodes:

常用键码：

40 = Return/Enter

40 = 回车键/换行键

41 = Escape

41 = 退出键

42 = Backspace/Delete

42 = 退格键/删除键

43 = Tab

43 = 制表符

44 = Space

44 = 空格键

79 = Right Arrow

79 = 右箭头

80 = Left Arrow

80 = 左箭头

81 = Down Arrow

81 = 下箭头

82 = Up Arrow

82 = 上箭头

Key sequence with timing

带时间控制的按键序列

axe key-sequence 40 43 40 --delay 0.2 --udid $UDID
undefined
axe key-sequence 40 43 40 --delay 0.2 --udid $UDID
undefined

Hardware Buttons

硬件按键

bash
undefined
bash
undefined

Home button

主屏幕按键

axe button home --udid $UDID
axe button home --udid $UDID

Lock/Power button

锁屏/电源按键

axe button lock --udid $UDID
axe button lock --udid $UDID

Long press power (shutdown dialog)

长按电源键（调出关机对话框）

axe button lock --duration 3.0 --udid $UDID
axe button lock --duration 3.0 --udid $UDID

Side button (iPhone X+)

侧边按键（iPhone X及以上机型）

axe button side-button --udid $UDID
axe button side-button --udid $UDID

Siri

Siri

axe button siri --udid $UDID
axe button siri --udid $UDID

Apple Pay

Apple Pay

axe button apple-pay --udid $UDID
undefined
axe button apple-pay --udid $UDID
undefined

Screenshots

截图

bash
undefined
bash
undefined

Screenshot to auto-named file

截图到自动命名的文件

axe screenshot --udid $UDID
axe screenshot --udid $UDID

Output: screenshot_2026-01-11_143052.png

输出：screenshot_2026-01-11_143052.png

Screenshot to specific file

截图到指定文件

axe screenshot --output /tmp/my-screenshot.png --udid $UDID
axe screenshot --output /tmp/my-screenshot.png --udid $UDID

Screenshot to stdout (for piping)

截图输出到标准输出（用于管道操作）

axe screenshot --stdout --udid $UDID > screenshot.png
undefined
axe screenshot --stdout --udid $UDID > screenshot.png
undefined

Video Recording & Streaming

录屏与流传输

Record Video

录屏

bash
undefined
bash
undefined

Start recording (Ctrl+C to stop)

开始录屏（按Ctrl+C停止）

axe record-video --output /tmp/recording.mp4 --udid $UDID
axe record-video --output /tmp/recording.mp4 --udid $UDID

Record with quality settings

带质量设置的录屏

axe record-video --output /tmp/recording.mp4 --quality high --udid $UDID
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
undefined
axe record-video --output /tmp/recording.mp4 --scale 0.5 --udid $UDID
undefined

Stream Video

视频流传输

bash
undefined
bash
undefined

Stream at 10 FPS (default)

以10 FPS传输视频（默认）

axe stream-video --udid $UDID
axe stream-video --udid $UDID

Stream at specific framerate (1-30 FPS)

以特定帧率传输视频（1-30 FPS）

axe stream-video --fps 30 --udid $UDID
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
undefined
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格式
undefined

UI Inspection (describe-ui)

UI检查（describe-ui）

Critical for finding accessibility identifiers and labels.
对于查找无障碍标识符和标签至关重要。

Full Screen UI Tree

全屏UI树

bash
undefined
bash
undefined

Get complete accessibility tree

获取完整的无障碍树

axe describe-ui --udid $UDID
axe describe-ui --udid $UDID

Output includes:

输出内容包括：

- Element type (Button, TextField, StaticText, etc.)

- 元素类型（Button、TextField、StaticText等）

- Accessibility identifier

- 无障碍标识符

- Accessibility label

- 无障碍标签

- Frame (position and size)

- 框架（位置和大小）

- Enabled/disabled state

- 启用/禁用状态

undefined
undefined

Point-Specific UI Info

指定坐标的UI信息

bash
undefined
bash
undefined

Get element at specific coordinates

获取指定坐标处的元素信息

axe describe-ui --point 200,400 --udid $UDID
undefined
axe describe-ui --point 200,400 --udid $UDID
undefined

Example Output

示例输出

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

Common Workflows

常见工作流

Login Flow

登录流程

bash
UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)
bash
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
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
axe tap --id "passwordTextField" --udid $UDID axe type "password123" --udid $UDID

Tap login button

点击登录按钮

axe tap --id "loginButton" --udid $UDID
axe tap --id "loginButton" --udid $UDID

Wait and screenshot

等待并截图

sleep 2 axe screenshot --output /tmp/login-result.png --udid $UDID
undefined
sleep 2 axe screenshot --output /tmp/login-result.png --udid $UDID
undefined

Discover Elements Before Automating

自动化前发现元素

bash
undefined
bash
undefined

1. Get the UI tree

1. 获取UI树

axe describe-ui --udid $UDID > /tmp/ui-tree.json
axe describe-ui --udid $UDID > /tmp/ui-tree.json

2. Find elements (search for identifiers)

2. 查找元素（搜索标识符）

cat /tmp/ui-tree.json | jq '.[] | select(.identifier != null) | {identifier, label, type}'
cat /tmp/ui-tree.json | jq '.[] | select(.identifier != null) | {identifier, label, type}'

3. Use discovered identifiers in automation

3. 在自动化中使用发现的标识符

axe tap --id "discoveredIdentifier" --udid $UDID
undefined
axe tap --id "discoveredIdentifier" --udid $UDID
undefined

Scroll to Find Element

滚动查找元素

bash
undefined
bash
undefined

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
undefined
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
undefined

Screenshot on Error

错误时截图

bash
undefined
bash
undefined

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
undefined
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
undefined

Timing Controls

时间控制

Most commands support timing options:
OptionDescription
--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)
bash
undefined
大多数命令支持时间选项：
选项描述
--pre-delay
操作前等待时间（秒）
--post-delay
操作后等待时间（秒）
--duration
操作持续时间（适用于点击、按键）
--char-delay
字符间输入延迟（适用于文本输入）
bash
undefined

Example with full timing control

带完整时间控制的示例

axe tap --id "button" --pre-delay 0.5 --post-delay 0.3 --udid $UDID
undefined
axe tap --id "button" --pre-delay 0.5 --post-delay 0.3 --udid $UDID
undefined

AXe vs simctl

AXe 与 simctl对比

CapabilitysimctlAXe
Device lifecycle✅❌
Permissions✅❌
Push notifications✅❌
Status bar✅❌
Deep links✅❌
Screenshots✅✅ (PNG)
Video recording✅✅ (H.264)
Video streaming❌✅
UI tap/swipe❌✅
Type text❌✅
Hardware buttons❌✅
Accessibility tree❌✅
Use both together: simctl for device control, AXe for UI automation.
功能simctlAXe
设备生命周期✅❌
权限设置✅❌
推送通知✅❌
状态栏✅❌
深度链接✅❌
截图✅✅ (PNG)
录屏✅✅ (H.264)
视频流传输❌✅
UI点击/滑动❌✅
文本输入❌✅
硬件按键操作❌✅
无障碍树❌✅
结合使用两者：simctl用于设备控制，AXe用于UI自动化。

Troubleshooting

故障排除

Element Not Found

元素未找到

  1. Run 
    axe describe-ui
    to see available elements
  2. Check element has 
    accessibilityIdentifier
    set in code
  3. Ensure element is visible (not off-screen)
  1. 运行
    axe describe-ui
    查看可用元素
  2. 检查代码中是否设置了
    accessibilityIdentifier
  3. 确保元素可见（未超出屏幕范围）

Tap Doesn't Work

点击无效

  1. Check element is enabled (
    "enabled": true
    in describe-ui)
  2. Try adding 
    --pre-delay 0.5
    for slow-loading UI
  3. Verify correct UDID with 
    axe list-simulators
  1. 检查元素是否已启用（在describe-ui输出中
    "enabled": true
    ）
  2. 尝试添加
    --pre-delay 0.5
    以适配加载缓慢的UI
  3. 通过
    axe list-simulators
    验证UDID是否正确

Type Not Working

文本输入无效

  1. Ensure text field is focused first: 
    axe tap --id "textField"
  2. Check keyboard is visible
  3. Try 
    --char-delay 0.05
    for reliability
  1. 确保文本框已获得焦点：
    axe tap --id "textField"
  2. 检查键盘是否可见
  3. 尝试使用
    --char-delay 0.05
    以提高可靠性

Permission Denied

权限被拒绝

AXe uses private APIs - ensure you're running on a Mac with Xcode installed and proper entitlements.
AXe使用私有API - 确保你在安装了Xcode的Mac上运行，并且拥有适当的权限。

Resources

资源

GitHub: https://github.com/cameroncooke/AXe
Related: xcsentinel (build orchestration)
Skills: axiom-xctest-automation, axiom-ui-testing
Agents: simulator-tester, test-runner
GitHub：https://github.com/cameroncooke/AXe
相关工具：xcsentinel（构建编排）
技能：axiom-xctest-automation, axiom-ui-testing
代理：simulator-tester, test-runner