29 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
ios-simulator-skill
version
1.5.0
description
29 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.
iOS Simulator Skill
Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.
Quick Start
# 1. Check environment
bash scripts/sim_health_check.sh
# 2. Launch app
python scripts/app_launcher.py --launch com.example.app
# 3. Map screen to see elements
python scripts/screen_mapper.py
# 4. Tap button
python scripts/navigator.py --find-text "Login" --tap
# 5. Enter text
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.
Navigation Strategy
Always prefer the accessibility tree over screenshots for navigation. The accessibility tree gives you element types, labels, frames, and tap targets — structured data that's cheaper and more reliable than image analysis.
Use this priority:
screen_mapper.py → structured element list (5-7 lines, ~10 tokens)
--get-details SESSION_ID on a raw session prints the path with a zcat | jq ... hint
Resilience (auto-restart on stream death): EOF or subprocess death triggers a stream_died event then a bounded restart with 2s backoff. After IOS_SIM_HANG_MAX_RESTARTS (default 3) the session is marked crashed, never left in stale running state. --list-sessions shows capture=Xs and restarts=N.
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.
Screenshot Sizing: Screenshots are resized to save tokens. Presets: full (3-4 tiles, ~5K tokens), half (1 tile, ~1.6K tokens, default), quarter (1 tile, ~800 tokens, less detail). Use quarter for quick visual checks, half for readable UI, full only when pixel-level detail matters. Scripts that capture screenshots (app_state_capture.py, test_recorder.py) default to half.
Debug if needed: python scripts/app_state_capture.py --app-bundle-id com.example.app
Configuration
Most operational limits can be tuned via environment variables. Defaults work for typical local development; raise them for slow CI runners, large monorepo builds, or accessibility audits on complex screens.
Variable
Default
Controls
IOS_SIM_A11Y_LABEL_MAX
80
Max chars of AXLabel retained in accessibility audit output
IOS_SIM_A11Y_TOP_ISSUES
10
Top accessibility issues surfaced per audit
IOS_SIM_APPS_PREVIEW
30
App entries listed by app_launcher.py before truncation
IOS_SIM_BOOT_SUBPROCESS_TIMEOUT
60
Timeout for the simctl boot subprocess itself (seconds)
IOS_SIM_BOOT_TIMEOUT
300
Wait-for-ready timeout after boot (seconds)
IOS_SIM_BUILD_JSON_CAP
50
Max build errors / failed tests in JSON output
IOS_SIM_BUILD_LOG_PREVIEW
4000
Chars of build log preview in default output
IOS_SIM_BUILD_TIMEOUT
1800
Max seconds for an xcodebuild build invocation before kill
IOS_SIM_INTROSPECT_TIMEOUT
60
Timeout for xcodebuild -list and simctl list lookups (seconds)
IOS_SIM_TEST_TIMEOUT
2700
Max seconds for an xcodebuild test invocation before kill
IOS_SIM_BUILD_SUMMARY_CAP
15
Errors/failures in default build summary
IOS_SIM_BUILD_VERBOSE_CAP
100
Errors/warnings in verbose build output
IOS_SIM_CACHE_MAX_ENTRIES
500
Max entries in progressive disclosure cache (LRU eviction)
IOS_SIM_CACHE_TTL_HOURS
1
Cache entry expiration
IOS_SIM_ERASE_TIMEOUT
90
Wait-for-erase timeout (seconds)
IOS_SIM_HANG_PREDICATE
(default)
Override the os_log predicate used by hang_watcher.py (default catches RunningBoard kills + "Hang detected" + main-thread hangs). Hang events originate from system daemons (RunningBoard, SpringBoard) so the predicate stays simulator-global — --bundle-id is applied post-parse, not ANDed in.
IOS_SIM_HANG_MIN_MS
250
HangBuster threshold — events below this duration never reach disk (smaller = more sensitive, larger summaries)
IOS_SIM_HANG_SESSION_TTL_HOURS
24
HangBuster session prune age; pruning runs on every --start
IOS_SIM_HANG_DEFAULT_TOP_N
3
Default top-N clusters in --stop L1 output
IOS_SIM_HANG_BUDGET_TOKENS
(unset)
Default token budget for --stop (picks L0/L1/L2 to fit)
IOS_SIM_HANG_MAX_RESTARTS
3
HangBuster worker: max log stream respawn attempts on EOF/subprocess death before the session is marked crashed
IOS_SIM_HANG_TOTAL_CAP_MB
100
HangBuster aggregate disk cap. When total session-state exceeds this on --start, oldest sessions are dropped first. Set to 0 to disable.
IOS_SIM_LOG_JSON_CAP
100
Max errors/warnings in log_monitor.py JSON output
IOS_SIM_LOG_LINE_MAX
300
Per-line truncation in log summaries
IOS_SIM_LOG_TAIL
200
Lines of log tail in verbose / sample output
IOS_SIM_LOG_TEXT_SUMMARY
15
Errors/warnings shown in text-mode log summary
IOS_SIM_MAX_ELEMENTS
25
Tappable elements listed by navigator.py
IOS_SIM_POLL_INTERVAL
0.5
Boot/erase state polling interval (seconds)
IOS_SIM_RELAUNCH_DELAY_MS
1000
Delay between terminate and re-launch in app_launcher.py
IOS_SIM_SCREEN_BUTTONS_PREVIEW
15
Button names listed by screen_mapper.py
IOS_SIM_SCREEN_SECTION_ITEMS
10
Items per section shown by screen_mapper.py
IOS_SIM_STATE_SUBPROCESS_TIMEOUT
15
Subprocess timeout in app_state_capture.py (seconds)
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
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.
Cleanup is automatic: TTL prune (IOS_SIM_HANG_SESSION_TTL_HOURS, default 24h) + aggregate cap (IOS_SIM_HANG_TOTAL_CAP_MB, default 100 MB, oldest-first eviction) both run on every --start.
Legacy modes (unchanged for backward compat):--watch [--duration N] (live stream) and --since 5m (historical)
Filters: --bundle-id (post-parse — hang capture stays simulator-global so RunningBoard/SpringBoard events are kept), --predicate (also via IOS_SIM_HANG_PREDICATE)
All output supports --json; session storage at ~/.ios-simulator-skill/sessions/<id>/{meta.json,events.jsonl,summary.json,raw.ndjson.gz}
