axiom-axe-ref by charleswiltgen/axiom
npx skills add https://github.com/charleswiltgen/axiom --skill axiom-axe-refAXe 是一个使用 Apple 辅助功能 API 和 HID 功能与 iOS 模拟器交互的 CLI 工具。单一二进制文件,无需守护进程。
brew install cameroncooke/axe/axe
# 验证安装
axe --version
在进行 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 开发者,精准高效
describe-ui 的 -x -y 坐标 - 脆弱,仅在无标识符时使用AXe 的关键优势:通过辅助功能标识符或标签点击元素,而不仅仅是坐标。
# 基于坐标(脆弱 - 布局改变时会失效)
axe tap -x 200 -y 400 --udid $UDID
# 基于辅助功能(稳定 - 可承受 UI 变化)
axe tap --id "loginButton" --udid $UDID
axe tap --label "Login" --udid $UDID
始终优先使用 --id 或 --label 而非坐标。
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
对于查找辅助功能标识符和标签至关重要。
# 获取完整的辅助功能树
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
| 功能 | simctl | AXe |
|---|---|---|
| 设备生命周期 | ✅ | ❌ |
| 权限 | ✅ | ❌ |
| 推送通知 | ✅ | ❌ |
| 状态栏 | ✅ | ❌ |
| 深度链接 | ✅ | ❌ |
| 截图 | ✅ | ✅ (PNG) |
| 视频录制 | ✅ | ✅ (H.264) |
| 视频流传输 | ❌ | ✅ |
| UI 点击/滑动 | ❌ | ✅ |
| 输入文本 | ❌ | ✅ |
| 硬件按钮 | ❌ | ✅ |
| 辅助功能树 | ❌ | ✅ |
两者结合使用:simctl 用于设备控制,AXe 用于 UI 自动化。
axe describe-ui 查看可用元素accessibilityIdentifier"enabled": true)--pre-delay 0.5axe list-simulators 验证正确的 UDIDaxe tap --id "textField"--char-delay 0.05 以提高可靠性AXe 使用私有 API - 确保您在安装了 Xcode 的 Mac 上运行,并具有适当的权限。
相关:xcsentinel(构建编排)
技能:axiom-xctest-automation, axiom-ui-testing
代理:simulator-tester, test-runner
每周安装数
93
代码仓库
GitHub 星标数
601
首次出现
2026年1月21日
安全审计
安装于
opencode77
claude-code71
codex71
gemini-cli70
cursor69
github-copilot67
AXe is a CLI tool for interacting with iOS Simulators using Apple's Accessibility APIs and HID functionality. Single binary, no daemon required.
brew install cameroncooke/axe/axe
# Verify installation
axe --version
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 identifierAXe'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.
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
# 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 "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
# 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
Critical for finding accessibility identifiers and labels.
# 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
# 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 "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
# 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
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
| 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.
axe describe-ui to see available elementsaccessibilityIdentifier set in code"enabled": true in describe-ui)--pre-delay 0.5 for slow-loading UIaxe list-simulatorsaxe tap --id "textField"--char-delay 0.05 for reliabilityAXe uses private APIs - ensure you're running on a Mac with Xcode installed and proper entitlements.
GitHub : https://github.com/cameroncooke/AXe
Related : xcsentinel (build orchestration)
Skills : axiom-xctest-automation, axiom-ui-testing
Agents : simulator-tester, test-runner
Weekly Installs
93
Repository
GitHub Stars
601
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykFail
Installed on
opencode77
claude-code71
codex71
gemini-cli70
cursor69
github-copilot67
通过 LiteLLM 代理让 Claude Code 对接 GitHub Copilot 运行 | 高级变通方案指南
36,300 周安装
characteristic-voice:为AI助手注入真实情感与个性语音,打造会叹息会笑的伙伴
2,100 周安装
YouTube 字幕提取工具 - 一键获取视频字幕/时间戳,支持自动与手动字幕
2,100 周安装
Karpathy LLM 编码指南 - 减少AI编程错误的行为准则与最佳实践
2,100 周安装
ElevenLabs 语音转文字 API - 支持 90+ 语言、说话人分离和词级时间戳的音频转录
2,200 周安装
Three.js交互开发指南:Raycaster光线投射与鼠标点击检测实现3D交互
2,100 周安装
OpenClaw备份技能:为Agent工作区提供自动加密备份与恢复解决方案
2,200 周安装
| ❌ |
| ✅ |
| Accessibility tree | ❌ | ✅ |