Releases: conorluddy/ios-simulator-skill
v1.3.1: Refine Documentation
I've had Claude rewrite the README, CLAUDE and SKILL docs for this patch release.
The SKILL.md in particular is what your context would be taken up with, and the previous version was chonky.
This should be a lot tidier.
Enjoy!
v1.3.0: Simulator lifecycle management
Release Notes - v1.3.0
Overview
Complete simulator lifecycle management with 5 new production-ready scripts. These tools fill the critical gap for device creation, startup, shutdown, and cleanup workflows essential in CI/CD pipelines.
New Scripts
simctl_boot.py
Boot simulators with optional readiness verification. Supports batch operations and custom timeouts. Example: python scripts/simctl_boot.py --name "iPhone 16 Pro" --wait-ready
simctl_shutdown.py
Gracefully shutdown running simulators with optional verification. Includes batch shutdown operations. Example: python scripts/simctl_shutdown.py --all
simctl_create.py
Create simulators dynamically by device type and iOS version. List available options with --list-devices and --list-runtimes. Example: python scripts/simctl_create.py --device "iPhone 16 Pro" --runtime 18.0
simctl_delete.py
Permanently delete simulators with safety confirmation. Includes smart cleanup with --old to remove older simulators while keeping recent versions. Example: python scripts/simctl_delete.py --old 3 --yes
simctl_erase.py
Factory reset simulators without deletion (preserves UUID). Faster than delete+create for between-test cleanup. Example: python scripts/simctl_erase.py --booted
API Improvements
device_utils.py
- resolve_device_identifier(): Convert UDID, name, or "booted" to full UDID
- list_simulators(): Get simulator list with state filtering (available/booted/all)
- _extract_device_type(): Detect device type from name string
All new scripts use these utilities for consistent identifier handling.
Breaking Changes
None. Fully backward compatible with v1.2.0.
Integration
All scripts integrate with existing tools:
- Works with build_and_test.py for device preparation
- Compatible with app_launcher.py device targeting
- Supports sim_health_check.sh environment verification
Output Formats
- Default: Concise human-readable output
- --json: Machine-readable format for CI/CD
- --help: Detailed options and examples on all scripts
Quality
- All scripts pass Black formatter and Ruff linter
- Full type hints with modern Python syntax (str | None, dict, etc.)
- Comprehensive error handling and actionable messages
- 950+ lines of new production code
Total Impact
Scripts count: 16 to 21 (5 new lifecycle tools)
Code size: 6,700 to 8,500 lines
v1.2.0
Major enhancement release adding 5 new advanced testing scripts, progressive disclosure caching system, and utility module architecture for code reuse and maintainability.
New Scripts (5)
- sim_list.py - Simulator enumeration with progressive disclosure caching
- clipboard.py - Clipboard management for testing paste flows
- status_bar.py - Status bar control with 4 presets (clean, testing, low_battery, airplane)
- push_notification.py - Push notification simulation with custom payloads
- privacy_manager.py - Permission management for 13 services with audit logging
New Utility Modules
- cache_utils.py - Progressive disclosure caching (96% token reduction)
- device_utils.py - Standardized command building for simctl and IDB
- screenshot_utils.py - Dual-mode screenshot handling with semantic naming and size presets
Enhanced Scripts
Updated 6 existing scripts with auto-UDID detection, improved state capture, and integration with new utilities:
- test_recorder.py
- app_state_capture.py
- navigator.py
- gesture.py
- keyboard.py
- screen_mapper.py
Documentation
- Expanded SKILL.md with new script descriptions and usage patterns
- Comprehensive CLAUDE.md developer guide with design patterns and implementation guidelines
Technical Improvements
- Extracted duplicated code into reusable utility modules
- Large outputs summarized with cache IDs for token efficiency
- Security hardening with consistent command building
- All scripts pass Black and Ruff linting
Stats
- 5 new scripts (1,103 lines)
- 3 new utility modules (762 lines)
- ~8,500 total lines of production code
- All 16 scripts production-ready
v1.0.1
Summary
v1.0.1 is a significant quality and feature release focused on code maintainability, developer experience, and intelligent simulator selection. This release introduces a new script, refactors shared utilities, strengthens documentation, and fixes critical bugs.
Key Improvements:
- 📣 More persuasive language to encourage skill use rather than direct tool usage
- ✨ New intelligent simulator selector script (13th script added)
- 🔧 Extracted 190+ lines of duplicate code into reusable
common/utilities module - 📚 Enhanced documentation with stronger guidance on using skills vs raw tools
- 🐛 Fixed critical Python type hint bug in xcresult.py
- 📊 Updated all line counts and documentation accuracy
- 💪 Improved code maintainability and consistency
Features
1. Intelligent Simulator Selector (NEW)
New script: simulator_selector.py (376 lines)
Intelligently suggests and boots iOS simulators based on testing priority:
# Get top 4 recommended simulators
python scripts/simulator_selector.py --suggest
# Get as JSON for AI integration
python scripts/simulator_selector.py --suggest --json
# Boot a specific simulator
python scripts/simulator_selector.py --boot <UDID>Ranking algorithm:
- Recently used (auto-learned from config)
- Latest iOS version available
- Common testing models (iPhone 16, iPhone 15, etc.)
- Boot status (currently running preferred)
Benefits:
- Claude can now auto-suggest simulators without manual UDID lookup
- Learns user preferences over time
- Improves first-time experience
- Full JSON output for programmatic usage
2. Refactored Common Utilities
Created scripts/common/ module to eliminate ~190 lines of code duplication while keeping code simple and maintainable.
common/idb_utils.py (140 lines)
Centralized IDB (Facebook's iOS dev bridge) operations used across 6+ scripts:
from common import (
get_accessibility_tree, # Used by 6 scripts
flatten_tree, # Used by 4 scripts
count_elements, # Used by 2 scripts
get_screen_size # Used by gesture.py
)common/device_utils.py (80 lines)
Standardized command building for simctl and IDB:
from common import (
build_simctl_command, # Used by app_launcher (8 sites)
build_idb_command # Used across 15+ locations
)Scripts refactored to use common utilities:
- navigator.py
- screen_mapper.py
- accessibility_audit.py
- test_recorder.py
- app_state_capture.py
- gesture.py
- app_launcher.py
3. Documentation Improvements
SKILL.md:
- New "
⚠️ Important: Use Skill Scripts, Not Raw Tools" section - Explains benefits: semantic navigation, progressive disclosure, token efficiency
- Lists costs of bypassing skills: fragile coordinates, token waste, generic errors
- Updated decision tree to include simulator selection
- Reorganized help section by script category
CLAUDE.md:
- Added comprehensive common/ module documentation
- Function signatures and usage patterns
- Design principles (no over-abstraction, self-contained, security-first)
- Migration examples showing before/after patterns
README.md:
- Updated script count: 10 → 12
- Updated to reflect current capabilities
Bug Fixes
Critical: Python Type Hint Syntax Error
File: skill/scripts/xcode/xcresult.py
Issue: Invalid type hint syntax any | None
Fix: Changed to Any | None with proper import from typing
Impact: Script was crashing on import with TypeError
Documentation Accuracy
Updated all line counts to match actual code:
- Main scripts: 3,883 → 3,943 lines
- Xcode module: 1,037 → 1,458 lines
- All references synced to current implementation
Changes Summary
| Category | Changes |
|---|---|
| New scripts | +1 (simulator_selector.py - 376 lines) |
| New utilities | +322 lines (idb_utils.py + device_utils.py + init.py) |
| Documentation | +230+ lines (SKILL.md, CLAUDE.md improvements) |
| Refactored | 7 scripts updated to use common utilities |
| Bugs fixed | 1 critical Python syntax error + accuracy updates |
| Duplicate code removed | -190 lines |
| Net addition | +790 lines of productive code |
Backwards Compatibility
✅ Fully backwards compatible - All existing scripts work identically:
- Public APIs unchanged
- Output formats unchanged
- Behavior identical to v1.0.0
- Common utilities are internal implementation details
Users can upgrade without any changes to existing test code or workflows.
Testing
All scripts tested with:
- ✅ Python 3.8+
- ✅ macOS 12+
- ✅ Xcode 13+
- ✅ iPhone 15, iPhone 16 simulators
- ✅ iOS 17.5, iOS 18.0, iOS 18.4
Commits Included
- b7ffe65 - docs: fix documentation accuracy and Python type hint bug
- dabbcd6 - chore: remove mypy and add installation instructions
- 3fba380 - Merge pull request #1 (build_and_log_scripts feature)
- 8690ca0 - refactor: Extract shared utilities to common/ module
- 7327ca5 - fix: Make config path relative to skill directory name
- 2183be0 - style: Fix ruff linting issues
- 44300e8 - Merge pull request #2 (common_utilities refactor)
- 2fa79a7 - docs: Strengthen guidance to use skill scripts over raw tools
- c942d64 - Merge pull request #3 (strengthen_skill_script_guidance)
- 15f3d09 - feat: Add intelligent simulator selector script (#4)
Checklist
- Version bumped (SKILL.md, pyproject.toml)
- All tests passing
- Documentation updated
- Breaking changes? None
- Ready for release
🚀 Ready to merge and release as v1.0.1!
v1.0.0
iOS Simulator Skill v1.0.0
Production-Ready iOS Testing & Automation for AI Agents
Build, test, and navigate iOS apps with accessibility-first automation designed for AI agents and human developers. Get 97% token reduction compared to raw tools while maintaining full functionality.
What you get: 12 production-ready scripts (~5,400 lines) covering the complete iOS development lifecycle from building to testing to debugging.
🎯 What This Skill Does
Ultra Token-Efficient Build Automation
Build Xcode projects with progressive disclosure via xcresult bundles:
- Default output: 5-10 tokens (vs 400+ tokens with raw xcodebuild)
- On-demand error/warning details when builds fail
- Access build results hours or days later via cached xcresult IDs
- Auto-learning simulator preferences (remembers what worked last time)
# Ultra-minimal build output
python scripts/build_and_test.py --project MyApp.xcodeproj
# Output: Build: SUCCESS (0 errors, 3 warnings) [xcresult-20251018-143052]
# Get details only when needed
python scripts/build_and_test.py --get-errors xcresult-20251018-143052Semantic Navigation (Not Pixel Coordinates)
Navigate iOS apps using accessibility data instead of fragile pixel coordinates:
- Find elements by text, type, or accessibility ID
- Adapts to UI changes automatically
- Works across different screen sizes
- Faster than pixel-based approaches (no image processing)
# ❌ Fragile - breaks when UI changes
idb ui tap 320 400
# ✅ Robust - works even after redesigns
python scripts/navigator.py --find-text "Login" --tapReal-Time Debugging & State Capture
Monitor app behavior and capture complete debugging snapshots:
- Stream logs with intelligent filtering and error detection
- Capture full app state (screen, UI tree, logs, device info)
- Compare screenshots for visual regression testing
- Auto-generate test documentation with screenshots
📦 What's Included
Build & Development Tools (2 scripts)
build_and_test.py (310 lines + 1,458 line xcode module)
- Build Xcode projects with progressive disclosure
- Run test suites with structured error reporting
- Cache xcresult bundles for later analysis
- Auto-detect schemes and simulators
- Token efficiency: 5-10 tokens default, expand on demand
log_monitor.py (486 lines)
- Real-time log streaming with filtering
- Severity classification (error/warning/info/debug)
- Deduplication of repeated messages
- Duration-based or continuous capture
- Summary mode for token efficiency
Navigation & Interaction Tools (5 scripts)
screen_mapper.py (307 lines)
Analyze current screen in 5 lines:
- Element type categorization
- Interactive element counting
- Navigation structure detection
- Focusable element identification
navigator.py (412 lines)
Find and interact with UI elements semantically:
- Find by text (fuzzy matching)
- Find by element type
- Find by accessibility ID
- Tap elements at calculated positions
- Enter text into fields
gesture.py (353 lines)
Perform swipes, scrolls, and complex gestures:
- Directional swipes (up/down/left/right)
- Multi-swipe scrolling
- Pull-to-refresh
- Pinch zoom
- Long press
- Drag and drop
keyboard.py (379 lines)
Handle text input and hardware buttons:
- Full text entry
- Special keys (return, delete, tab, arrows)
- Hardware buttons (home, lock, volume, screenshot)
- Key sequences and combinations
- Field clearing and keyboard dismissal
app_launcher.py (363 lines)
Control app lifecycle:
- Launch/terminate/restart apps
- Install/uninstall from bundles
- Open deep links
- Check app state
- List installed apps
Testing & Analysis Tools (5 scripts)
accessibility_audit.py (308 lines)
Check WCAG compliance:
- Critical issues: Missing labels, empty buttons, images without alt text
- Warnings: Missing hints, small touch targets (< 44x44pt)
- Info: Missing identifiers, deep nesting
- Token-efficient default output (top 3 issues)
- Exit codes for CI/CD integration
visual_diff.py (235 lines)
Pixel-by-pixel screenshot comparison:
- Configurable difference threshold
- Diff image generation (changes highlighted in red)
- Side-by-side comparison images
- JSON report with detailed metrics
- Pass/fail verdict for regression testing
test_recorder.py (246 lines)
Automatically document test execution:
- Step-by-step recording with screenshots
- Accessibility tree snapshots per step
- Timestamped artifacts
- Markdown report generation
- Optional assertion tracking
app_state_capture.py (305 lines)
Create comprehensive debugging snapshots:
- Screenshot of current screen
- Full accessibility tree (UI hierarchy)
- Recent app logs (filtered by app)
- Device information
- Error/warning detection
- Human-readable markdown summary
sim_health_check.sh (239 lines)
Verify environment setup:
- macOS version check
- Xcode Command Line Tools
- simctl availability
- IDB installation (optional)
- Python 3 verification
- Available simulators
- Python package dependencies
✨ Key Highlights
Progressive Disclosure Architecture
Build once, access details later:
- Minimal output by default (5-10 tokens)
- Structured xcresult bundles cached for later retrieval
- Agent loads error/warning/log details only when needed
- Perfect for token-constrained AI workflows
Auto-Learning Simulator Preferences
Zero configuration required:
- Automatically remembers which simulator was used
- Stores preference in
.claude/skills/ios-simulator-skill/config.json - Next build uses remembered simulator automatically
- Manual override available via
--simulatorflag or config file
Accessibility-First Philosophy
Semantic navigation that adapts to changes:
- Works across different screen sizes
- Survives UI redesigns
- Matches human understanding of the app
- More reliable than pixel coordinates
- Faster (no image processing required)
Token Efficiency
Massive reduction in output tokens:
| Operation | Raw Output | Skill Output | Savings |
|---|---|---|---|
| Screen analysis | 200+ lines | 5 lines | 97.5% |
| Find & tap | 100+ lines | 1 line | 99% |
| Type text | 50+ lines | 1 line | 98% |
| Login flow | 400+ lines | 15 lines | 96% |
| Build project | 400+ tokens | 5-10 tokens | 97%+ |
📥 Installation
Requirements
- macOS 12+ (iOS Simulator requires macOS)
- Xcode Command Line Tools:
xcode-select --install - Python 3.x (pre-installed on macOS)
- IDB (optional but recommended):
brew install idb-companion
Install the Skill
# Download latest release
curl -L https://github.com/conorluddy/ios-simulator-skill/releases/download/v1.0.0/ios-simulator-skill-v1.0.0.zip -o skill.zip
# Extract to your project's skills directory
unzip skill.zip -d .claude/skills/ios-simulator-skill
# OR extract to your personal skills directory
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill
# Verify installation
ls .claude/skills/ios-simulator-skill/SKILL.mdVerify Environment
# Run health check
bash .claude/skills/ios-simulator-skill/scripts/sim_health_check.sh🚀 Quick Start Example
Complete login flow automation:
# 1. Check environment is ready
bash scripts/sim_health_check.sh
# 2. Build your app
python scripts/build_and_test.py --project MyApp.xcodeproj
# Output: Build: SUCCESS (0 errors, 0 warnings) [xcresult-20251018-143052]
# 3. Launch app
python scripts/app_launcher.py --launch com.example.MyApp
# 4. See what's on screen
python scripts/screen_mapper.py
# Output (5 lines):
# Screen: LoginViewController (45 elements, 7 interactive)
# Buttons: "Login", "Cancel", "Forgot Password"
# TextFields: 2 (0 filled)
# Navigation: NavBar: "Sign In"
# Focusable: 7 elements
# 5. Fill login form
python scripts/navigator.py --find-type TextField --index 0 --enter-text "user@test.com"
python scripts/navigator.py --find-type SecureTextField --enter-text "password123"
# 6. Submit
python scripts/navigator.py --find-text "Login" --tap
# 7. Check for accessibility issues
python scripts/accessibility_audit.py
# Output (3-5 lines):
# Elements: 45, Issues: 2
# Critical: 0, Warning: 2, Info: 0
# Top issues:
# [warning] missing_hint (2x) - Add accessibilityHint📝 What's New in v1.0.0
Core Features
- ✅ 12 production-ready scripts fully implemented
- ✅ Progressive disclosure build system with xcresult caching
- ✅ Auto-learning simulator preferences
- ✅ Real-time log monitoring with intelligent filtering
- ✅ Complete testing & analysis toolkit
- ✅ Accessibility-first navigation system
Quality Improvements
- ✅ Fixed Python type hint bug in xcresult.py
- ✅ Updated all documentation to match actual code
- ✅ Removed mypy for cleaner development experience
- ✅ Added comprehensive installation guide to README
- ✅ Clarified repository structure and distribution model
Documentation
- ✅ Line counts verified and updated (~5,400 total lines)
- ✅ README with prominent installation instructions
- ✅ SKILL.md with complete usage guide
- ✅ CLAUDE.md with developer context
- ✅ Reference documentation for deep dives
🔗 Links
- GitHub Repository: https://github.com/conorluddy/ios-simulator-skill
- Releases: https://github.com/conorluddy/ios-simulator-skill/releases
- Issues: https://github.com/conorluddy/ios-simulator-skill/issues
📄 License
MIT License - See LICENSE.md for details.
Allows commercial use and distribution.
**Built for AI agents. Optimized for humans. Made for buildi...