axiom-axe-ref

Name: axiom-axe-ref
Author: charleswiltgen

github.com/charleswiltgen测试与质量1.2k170 次安装今天更新

代码仓库

关于 axiom-axe-ref

axiom-axe-ref 是 AXe 的参考指南，面向需要自动化操作 iOS 模拟器界面的开发者和测试人员。它介绍基于辅助功能标识符与标签的交互，以及手势、输入、界面检查和录屏等命令。

主要功能

01按辅助功能标识符或标签操作界面
02检查界面树及元素坐标
03执行点击、滑动和手势
04输入文本并控制硬件按钮
05截屏、录制和串流视频

适用场景

01自动化 iOS 模拟器中的登录流程
02查找界面元素后执行稳定的点击
03复现并记录模拟器中的问题
04为界面自动化测试采集截图或视频

安装

复制下面的命令，在终端中运行。

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

安装后在 Claude Code 中输入/axiom-axe-ref确认已加载。

详细介绍

AXe 参考（iOS Simulator UI 自动化）

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

安装

brew install cameroncooke/axe/axe

# Verify installation
axe --version

重要最佳实践：先运行 describe_ui

务必在与 UI 交互前运行 describe_ui。 切勿根据屏幕截图猜测坐标。

最佳实践： 使用 describe-ui 获取精确的元素坐标，然后再使用 x/y 参数（不要根据屏幕截图猜测）。

# 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

元素定位优先级：

--id（accessibilityIdentifier）——最稳定
--label（辅助功能标签）——稳定，但可能随本地化而变化
-x -y 来自 describe-ui 的坐标——不可靠，仅在没有标识符时使用

核心概念：辅助功能优先

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 控制设备，使用 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 上运行。

资源

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

相关工具：xcsentinel（构建编排）

技能：axiom-xctest-automation、axiom-ui-testing

Agent：simulator-tester、test-runner

支持 Markdown

登录后评论

基本信息

作者: charleswiltgen
仓库: charleswiltgen/axiom
分类: 测试与质量
安装次数: 170
GitHub Stars: 1,231

报告问题