ios-simulator-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Simulator Skill

iOS Simulator 技能工具集

Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.

通过无障碍驱动的导航和结构化数据而非像素坐标，来构建、测试和自动化iOS应用。

Quick Start

快速开始

bash

undefined

bash

undefined

1. Check environment

1. 检查环境

bash scripts/sim_health_check.sh

2. Launch app

2. 启动应用

python scripts/app_launcher.py --launch com.example.app

3. Map screen to see elements

3. 映射屏幕查看元素

python scripts/screen_mapper.py

4. Tap button

4. 点击按钮

python scripts/navigator.py --find-text "Login" --tap

5. Enter text

5. 输入文本

python scripts/navigator.py --find-type TextField --enter-text "user@example.com"


All scripts support `--help` for detailed options and `--json` for machine-readable output.

python scripts/navigator.py --find-type TextField --enter-text "user@example.com"


所有脚本均支持`--help`查看详细选项，以及`--json`输出机器可读格式的内容。

21 Production Scripts

21个生产可用脚本

Build & Development (2 scripts)

构建与开发（2个脚本）

build_and_test.py - Build Xcode projects, run tests, parse results with progressive disclosure
- Build with live result streaming
- Parse errors and warnings from xcresult bundles
- Retrieve detailed build logs on demand
- Options:
```
--project
```
  ,
```
--scheme
```
  ,
```
--clean
```
  ,
```
--test
```
  ,
```
--verbose
```
  ,
```
--json
```
log_monitor.py - Real-time log monitoring with intelligent filtering
- Stream logs or capture by duration
- Filter by severity (error/warning/info/debug)
- Deduplicate repeated messages
- Options:
```
--app
```
  ,
```
--severity
```
  ,
```
--follow
```
  ,
```
--duration
```
  ,
```
--output
```
  ,
```
--json
```

build_and_test.py - 构建Xcode项目、运行测试、通过渐进式披露解析结果
- 实时流式输出构建结果
- 解析xcresult包中的错误与警告信息
- 按需获取详细构建日志
- 选项：
```
--project
```
  ,
```
--scheme
```
  ,
```
--clean
```
  ,
```
--test
```
  ,
```
--verbose
```
  ,
```
--json
```
log_monitor.py - 带智能过滤功能的实时日志监控
- 流式输出日志或按时长捕获
- 按严重级别过滤（错误/警告/信息/调试）
- 去重重复消息
- 选项：
```
--app
```
  ,
```
--severity
```
  ,
```
--follow
```
  ,
```
--duration
```
  ,
```
--output
```
  ,
```
--json
```

Navigation & Interaction (5 scripts)

导航与交互（5个脚本）

screen_mapper.py - Analyze current screen and list interactive elements
- Element type breakdown
- Interactive button list
- Text field status
- Options:
```
--verbose
```
  ,
```
--hints
```
  ,
```
--json
```
navigator.py - Find and interact with elements semantically
- Find by text (fuzzy matching)
- Find by element type
- Find by accessibility ID
- Enter text or tap elements
- Options:
```
--find-text
```
  ,
```
--find-type
```
  ,
```
--find-id
```
  ,
```
--tap
```
  ,
```
--enter-text
```
  ,
```
--json
```
gesture.py - Perform swipes, scrolls, pinches, and complex gestures
- Directional swipes (up/down/left/right)
- Multi-swipe scrolling
- Pinch zoom
- Long press
- Pull to refresh
- Options:
```
--swipe
```
  ,
```
--scroll
```
  ,
```
--pinch
```
  ,
```
--long-press
```
  ,
```
--refresh
```
  ,
```
--json
```
keyboard.py - Text input and hardware button control
- Type text (fast or slow)
- Special keys (return, delete, tab, space, arrows)
- Hardware buttons (home, lock, volume, screenshot)
- Key combinations
- Options:
```
--type
```
  ,
```
--key
```
  ,
```
--button
```
  ,
```
--slow
```
  ,
```
--clear
```
  ,
```
--dismiss
```
  ,
```
--json
```
app_launcher.py - App lifecycle management
- Launch apps by bundle ID
- Terminate apps
- Install/uninstall from .app bundles
- Deep link navigation
- List installed apps
- Check app state
- Options:
```
--launch
```
  ,
```
--terminate
```
  ,
```
--install
```
  ,
```
--uninstall
```
  ,
```
--open-url
```
  ,
```
--list
```
  ,
```
--state
```
  ,
```
--json
```

screen_mapper.py - 分析当前屏幕并列出可交互元素
- 元素类型分类统计
- 可交互按钮列表
- 文本框状态
- 选项：
```
--verbose
```
  ,
```
--hints
```
  ,
```
--json
```
navigator.py - 通过语义化方式查找并与元素交互
- 通过文本查找（模糊匹配）
- 通过元素类型查找
- 通过无障碍ID查找
- 输入文本或点击元素
- 选项：
```
--find-text
```
  ,
```
--find-type
```
  ,
```
--find-id
```
  ,
```
--tap
```
  ,
```
--enter-text
```
  ,
```
--json
```
gesture.py - 执行滑动、滚动、捏合及复杂手势操作
- 定向滑动（上/下/左/右）
- 连续滑动滚动
- 捏合缩放
- 长按
- 下拉刷新
- 选项：
```
--swipe
```
  ,
```
--scroll
```
  ,
```
--pinch
```
  ,
```
--long-press
```
  ,
```
--refresh
```
  ,
```
--json
```
keyboard.py - 文本输入与硬件按钮控制
- 文本输入（快速或慢速）
- 特殊按键（回车、删除、制表符、空格、方向键）
- 硬件按钮（主页、锁屏、音量、截图）
- 组合按键
- 选项：
```
--type
```
  ,
```
--key
```
  ,
```
--button
```
  ,
```
--slow
```
  ,
```
--clear
```
  ,
```
--dismiss
```
  ,
```
--json
```
app_launcher.py - 应用生命周期管理
- 通过Bundle ID启动应用
- 终止应用进程
- 从.app包安装/卸载应用
- 深度链接导航
- 列出已安装应用
- 检查应用状态
- 选项：
```
--launch
```
  ,
```
--terminate
```
  ,
```
--install
```
  ,
```
--uninstall
```
  ,
```
--open-url
```
  ,
```
--list
```
  ,
```
--state
```
  ,
```
--json
```

Testing & Analysis (5 scripts)

测试与分析（5个脚本）

accessibility_audit.py - Check WCAG compliance on current screen
- Critical issues (missing labels, empty buttons, no alt text)
- Warnings (missing hints, small touch targets)
- Info (missing IDs, deep nesting)
- Options:
```
--verbose
```
  ,
```
--output
```
  ,
```
--json
```
visual_diff.py - Compare two screenshots for visual changes
- Pixel-by-pixel comparison
- Threshold-based pass/fail
- Generate diff images
- Options:
```
--threshold
```
  ,
```
--output
```
  ,
```
--details
```
  ,
```
--json
```
test_recorder.py - Automatically document test execution
- Capture screenshots and accessibility trees per step
- Generate markdown reports with timing data
- Options:
```
--test-name
```
  ,
```
--output
```
  ,
```
--verbose
```
  ,
```
--json
```
app_state_capture.py - Create comprehensive debugging snapshots
- Screenshot, UI hierarchy, app logs, device info
- Markdown summary for bug reports
- Options:
```
--app-bundle-id
```
  ,
```
--output
```
  ,
```
--log-lines
```
  ,
```
--json
```
sim_health_check.sh - Verify environment is properly configured
- Check macOS, Xcode, simctl, IDB, Python
- List available and booted simulators
- Verify Python packages (Pillow)

accessibility_audit.py - 检查当前屏幕的WCAG合规性
- 严重问题（缺失标签、空按钮、无替代文本）
- 警告（缺失提示、触摸目标过小）
- 信息类提示（缺失ID、层级过深）
- 选项：
```
--verbose
```
  ,
```
--output
```
  ,
```
--json
```
visual_diff.py - 对比两张截图以检测视觉变化
- 逐像素对比
- 基于阈值的通过/失败判定
- 生成差异对比图
- 选项：
```
--threshold
```
  ,
```
--output
```
  ,
```
--details
```
  ,
```
--json
```
test_recorder.py - 自动记录测试执行过程
- 每一步捕获截图与无障碍树
- 生成带时间数据的Markdown报告
- 选项：
```
--test-name
```
  ,
```
--output
```
  ,
```
--verbose
```
  ,
```
--json
```
app_state_capture.py - 创建全面的调试快照
- 截图、UI层级、应用日志、设备信息
- 生成用于Bug报告的Markdown摘要
- 选项：
```
--app-bundle-id
```
  ,
```
--output
```
  ,
```
--log-lines
```
  ,
```
--json
```
sim_health_check.sh - 验证环境配置是否正确
- 检查macOS、Xcode、simctl、IDB、Python环境
- 列出可用及已启动的模拟器
- 验证Python包（Pillow）

Advanced Testing & Permissions (4 scripts)

高级测试与权限管理（4个脚本）

clipboard.py - Manage simulator clipboard for paste testing
- Copy text to clipboard
- Test paste flows without manual entry
- Options:
```
--copy
```
  ,
```
--test-name
```
  ,
```
--expected
```
  ,
```
--json
```
status_bar.py - Override simulator status bar appearance
- Presets: clean (9:41, 100% battery), testing (11:11, 50%), low-battery (20%), airplane (offline)
- Custom time, network, battery, WiFi settings
- Options:
```
--preset
```
  ,
```
--time
```
  ,
```
--data-network
```
  ,
```
--battery-level
```
  ,
```
--clear
```
  ,
```
--json
```
push_notification.py - Send simulated push notifications
- Simple mode (title + body + badge)
- Custom JSON payloads
- Test notification handling and deep links
- Options:
```
--bundle-id
```
  ,
```
--title
```
  ,
```
--body
```
  ,
```
--badge
```
  ,
```
--payload
```
  ,
```
--json
```
privacy_manager.py - Grant, revoke, and reset app permissions
- 13 supported services (camera, microphone, location, contacts, photos, calendar, health, etc.)
- Batch operations (comma-separated services)
- Audit trail with test scenario tracking
- Options:
```
--bundle-id
```
  ,
```
--grant
```
  ,
```
--revoke
```
  ,
```
--reset
```
  ,
```
--list
```
  ,
```
--json
```

clipboard.py - 管理模拟器剪贴板以测试粘贴流程
- 将文本复制到剪贴板
- 无需手动输入即可测试粘贴流程
- 选项：
```
--copy
```
  ,
```
--test-name
```
  ,
```
--expected
```
  ,
```
--json
```
status_bar.py - 覆盖模拟器状态栏显示
- 预设样式：干净模式（9:41，100%电量）、测试模式（11:11，50%电量）、低电量模式（20%）、飞行模式（离线）
- 自定义时间、网络、电量、WiFi设置
- 选项：
```
--preset
```
  ,
```
--time
```
  ,
```
--data-network
```
  ,
```
--battery-level
```
  ,
```
--clear
```
  ,
```
--json
```
push_notification.py - 发送模拟推送通知
- 简单模式（标题+内容+角标）
- 自定义JSON负载
- 测试通知处理与深度链接
- 选项：
```
--bundle-id
```
  ,
```
--title
```
  ,
```
--body
```
  ,
```
--badge
```
  ,
```
--payload
```
  ,
```
--json
```
privacy_manager.py - 授予、撤销与重置应用权限
- 支持13种服务（相机、麦克风、位置、通讯录、照片、日历、健康等）
- 批量操作（逗号分隔的服务列表）
- 带测试场景追踪的审计记录
- 选项：
```
--bundle-id
```
  ,
```
--grant
```
  ,
```
--revoke
```
  ,
```
--reset
```
  ,
```
--list
```
  ,
```
--json
```

Device Lifecycle Management (5 scripts)

设备生命周期管理（5个脚本）

simctl_boot.py - Boot simulators with optional readiness verification
- Boot by UDID or device name
- Wait for device ready with timeout
- Batch boot operations (--all, --type)
- Performance timing
- Options:
```
--udid
```
  ,
```
--name
```
  ,
```
--wait-ready
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--json
```
simctl_shutdown.py - Gracefully shutdown simulators
- Shutdown by UDID or device name
- Optional verification of shutdown completion
- Batch shutdown operations
- Options:
```
--udid
```
  ,
```
--name
```
  ,
```
--verify
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--json
```
simctl_create.py - Create simulators dynamically
- Create by device type and iOS version
- List available device types and runtimes
- Custom device naming
- Returns UDID for CI/CD integration
- Options:
```
--device
```
  ,
```
--runtime
```
  ,
```
--name
```
  ,
```
--list-devices
```
  ,
```
--list-runtimes
```
  ,
```
--json
```
simctl_delete.py - Permanently delete simulators
- Delete by UDID or device name
- Safety confirmation by default (skip with --yes)
- Batch delete operations
- Smart deletion (--old N to keep N per device type)
- Options:
```
--udid
```
  ,
```
--name
```
  ,
```
--yes
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--old
```
  ,
```
--json
```
simctl_erase.py - Factory reset simulators without deletion
- Preserve device UUID (faster than delete+create)
- Erase all, by type, or booted simulators
- Optional verification
- Options:
```
--udid
```
  ,
```
--name
```
  ,
```
--verify
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--booted
```
  ,
```
--json
```

simctl_boot.py - 启动模拟器并可验证就绪状态
- 通过UDID或设备名称启动
- 等待设备就绪（带超时设置）
- 批量启动操作（--all 所有模拟器，--type 指定设备类型）
- 性能计时
- 选项：
```
--udid
```
  ,
```
--name
```
  ,
```
--wait-ready
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--json
```
simctl_shutdown.py - 优雅关闭模拟器
- 通过UDID或设备名称关闭
- 可选验证关闭完成状态
- 批量关闭操作
- 选项：
```
--udid
```
  ,
```
--name
```
  ,
```
--verify
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--json
```
simctl_create.py - 动态创建模拟器
- 通过设备类型与iOS版本创建
- 列出可用设备类型与运行时环境
- 自定义设备命名
- 返回UDID用于CI/CD集成
- 选项：
```
--device
```
  ,
```
--runtime
```
  ,
```
--name
```
  ,
```
--list-devices
```
  ,
```
--list-runtimes
```
  ,
```
--json
```
simctl_delete.py - 永久删除模拟器
- 通过UDID或设备名称删除
- 默认需安全确认（使用--yes跳过）
- 批量删除操作
- 智能删除（--old N 保留每种设备类型的N个模拟器）
- 选项：
```
--udid
```
  ,
```
--name
```
  ,
```
--yes
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--old
```
  ,
```
--json
```
simctl_erase.py - 重置模拟器至出厂设置（无需删除）
- 保留设备UUID（比删除+创建更快）
- 擦除全部、指定类型或已启动的模拟器
- 可选验证操作
- 选项：
```
--udid
```
  ,
```
--name
```
  ,
```
--verify
```
  ,
```
--timeout
```
  ,
```
--all
```
  ,
```
--type
```
  ,
```
--booted
```
  ,
```
--json
```

Common Patterns

通用模式

Auto-UDID Detection: Most scripts auto-detect the booted simulator if --udid is not provided.

Device Name Resolution: Use device names (e.g., "iPhone 16 Pro") instead of UDIDs - scripts resolve automatically.

Batch Operations: Many scripts support

--all

for all simulators or

--type iPhone

for device type filtering.

Output Formats: Default is concise human-readable output. Use

--json

for machine-readable output in CI/CD.

Help: All scripts support

--help

for detailed options and examples.

自动UDID检测：若未提供--udid参数，大多数脚本会自动检测已启动的模拟器。

设备名称解析：可使用设备名称（如"iPhone 16 Pro"）替代UDID，脚本会自动解析。

批量操作：许多脚本支持

--all

操作所有模拟器，或

--type iPhone

按设备类型过滤。

输出格式：默认输出简洁的人类可读内容。在CI/CD中可使用

--json

获取机器可读格式输出。

帮助信息：所有脚本均支持

--help

查看详细选项与示例。

Typical Workflow

典型工作流

Verify environment:
```
bash scripts/sim_health_check.sh
```

Launch app:

python scripts/app_launcher.py --launch com.example.app

Analyze screen:
```
python scripts/screen_mapper.py
```

Interact:

python scripts/navigator.py --find-text "Button" --tap

Verify:
```
python scripts/accessibility_audit.py
```

Debug if needed:

python scripts/app_state_capture.py --app-bundle-id com.example.app

验证环境：
```
bash scripts/sim_health_check.sh
```

启动应用：

python scripts/app_launcher.py --launch com.example.app

分析屏幕：
```
python scripts/screen_mapper.py
```

交互操作：

python scripts/navigator.py --find-text "Button" --tap

验证合规性：
```
python scripts/accessibility_audit.py
```

如需调试：

python scripts/app_state_capture.py --app-bundle-id com.example.app

Requirements

环境要求

macOS 12+
Xcode Command Line Tools
Python 3
IDB (optional, for interactive features)

macOS 12及以上版本
Xcode命令行工具
Python 3
IDB（可选，用于交互功能）

Documentation

文档说明

SKILL.md (this file) - Script reference and quick start
README.md - Installation and examples
CLAUDE.md - Architecture and implementation details
references/ - Deep documentation on specific topics
examples/ - Complete automation workflows

SKILL.md（本文档）- 脚本参考与快速入门
README.md - 安装说明与示例
CLAUDE.md - 架构与实现细节
references/ - 特定主题的深度文档
examples/ - 完整的自动化工作流示例

Key Design Principles

核心设计原则

Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes.

Token Efficiency: Concise default output (3-5 lines) with optional verbose and JSON modes for detailed results.

Accessibility-First: Built on standard accessibility APIs for reliability and compatibility.

Zero Configuration: Works immediately on any macOS with Xcode. No setup required.

Structured Data: Scripts output JSON or formatted text, not raw logs. Easy to parse and integrate.

Auto-Learning: Build system remembers your device preference. Configuration stored per-project.

Use these scripts directly or let Claude Code invoke them automatically when your request matches the skill description.

语义化导航：通过元素含义（文本、类型、ID）而非像素坐标查找元素，可适配UI变更。

Token高效性：默认输出简洁（3-5行），可通过verbose和JSON模式获取详细结果。

无障碍优先：基于标准无障碍API构建，确保可靠性与兼容性。

零配置：在任何安装了Xcode的macOS设备上均可立即使用，无需额外配置。

结构化数据：脚本输出JSON或格式化文本，而非原始日志，便于解析与集成。

自动学习：构建系统会记住你的设备偏好，配置按项目存储。

你可以直接使用这些脚本，也可在你的请求符合技能描述时，让Claude Code自动调用它们。",