by conorluddy (community) · Claude Code, macOS 12+, Xcode Command Line Tools, Python 3, IDB (опционально), Pillow (опционально)

показать оригинал переведено ИИ

iOS Simulator Skill для Claude Code

Готовый к продакшену скилл для сборки, тестирования и автоматизации iOS-приложений. 27 скриптов, оптимизированных как для разработчиков-людей, так и для ИИ-агентов.

(Если вы предпочитаете MCP — XC-MCP)

Автоматизация сборки Xcode + симулятора

Этот скилл охватывает обе стороны разработки под iOS:

Сборка Xcode через xcodebuild — компиляция, тестирование и разбор результатов с постепенным раскрытием ошибок
Взаимодействие с симулятором через xcrun simctl и idb — семантическая навигация по UI, проверка доступности, управление жизненным циклом устройства

Если вам нужны только инструменты сборки Xcode без скриптов симулятора, см. версию в виде плагина: xclaude-plugin

Установка

Через Plugin Marketplace (рекомендуется)

В Claude Code:

/plugin marketplace add conorluddy/ios-simulator-skill
/plugin install ios-simulator-skill@conorluddy

Через Git Clone

# Personal installation
git clone https://github.com/conorluddy/ios-simulator-skill.git ~/.claude/skills/ios-simulator-skill

# Project installation
git clone https://github.com/conorluddy/ios-simulator-skill.git .claude/skills/ios-simulator-skill

Перезапустите Claude Code. Скилл загрузится автоматически.

Предварительные требования

macOS 12+
Инструменты командной строки Xcode (xcode-select --install)
Python 3
IDB (опционально, для интерактивных функций: brew tap facebook/fb && brew install idb-companion)
Pillow (опционально, для визуальных сравнений: pip3 install pillow)

Возможности

Сборка Xcode с постепенным раскрытием информации

Скрипт build_and_test.py оборачивает xcodebuild, обеспечивая экономный по токенам вывод. Сборка возвращает одну итоговую строку с идентификатором xcresult:

Build: SUCCESS (0 errors, 3 warnings) [xcresult-20251018-143052]

Затем детали можно запросить по мере необходимости:

python scripts/build_and_test.py --get-errors xcresult-20251018-143052
python scripts/build_and_test.py --get-warnings xcresult-20251018-143052
python scripts/build_and_test.py --get-log xcresult-20251018-143052

Это позволяет удерживать диалоги агента сфокусированными — никаких простыней вывода сборки, если вы их явно не запросили.

Навигация по симулятору через Accessibility

Вместо хрупких нажатий по пиксельным координатам вся навигация использует API доступности iOS для поиска элементов по смыслу:

# Fragile — breaks if UI changes
idb ui tap 320 400

# Robust — finds by meaning
python scripts/navigator.py --find-text "Login" --tap

Дерево доступности даёт структурированные данные (типы элементов, подписи, фреймы, цели нажатий) при выводе по умолчанию около 10 токенов против 1 600–6 300 токенов для скриншота. Подробнее о том, почему навигация с приоритетом доступности важна для ИИ-агентов, читайте в статье Приложения, доступные для ИИ.

Оптимизация расхода токенов на скриншоты

Когда нужны скриншоты (визуальная проверка, отчёты об ошибках, сравнения), скилл автоматически изменяет их размер и сжимает их, чтобы минимизировать затраты токенов. Вывод по умолчанию во всех 27 скриптах составляет 3–5 строк — сокращение на 96% по сравнению с сырым выводом инструментов.

Задача	Сырые инструменты	Этот скилл	Экономия
Анализ экрана	200+ строк	5 строк	97.5%
Поиск и нажатие кнопки	100+ строк	1 строка	99%
Процесс входа	400+ строк	15 строк	96%

Все 27 скриптов

Каждый скрипт поддерживает --help и --json. Полную справку см. в SKILL.md.

Сборка и разработка

Скрипт	Что делает	Основные флаги
`build_and_test.py`	Сборка проектов Xcode, запуск тестов, разбор бандлов xcresult	`--project`, `--scheme`, `--test`, `--get-errors`, `--get-warnings`
`log_monitor.py`	Мониторинг логов в реальном времени с фильтрацией по уровню критичности	`--app`, `--severity`, `--follow`, `--duration`

Состояние устройства

Скрипт	Что делает	Основные флаги
`appearance.py`	Переключение тёмного режима, динамического типа текста, локали, региона	`--theme`, `--text-size`, `--locale`, `--region`, `--reset`
`location.py`	Симуляция GPS-координат и запуск встроенных сценариев	`--lat`, `--lng`, `--city`, `--gpx`, `--list-scenarios`, `--clear`

Навигация и взаимодействие

Скрипт	Что делает	Основные флаги
`screen_mapper.py`	Анализ текущего экрана, перечисление интерактивных элементов	`--verbose`, `--hints`
`navigator.py`	Семантический поиск элементов и взаимодействие с ними	`--find-text`, `--find-type`, `--find-id`, `--tap`, `--enter-text`
`gesture.py`	Свайпы, прокрутки, щипки, долгое нажатие, обновление потягиванием	`--swipe`, `--scroll`, `--pinch`, `--long-press`, `--refresh`
`keyboard.py`	Ввод текста и управление аппаратными кнопками	`--type`, `--key`, `--button`, `--clear`, `--dismiss`
`app_launcher.py`	Запуск, завершение, установка приложений, открытие диплинков	`--launch`, `--terminate`, `--install`, `--open-url`, `--list`

Тестирование и анализ

Скрипт	Что делает	Основные флаги
`accessibility_audit.py`	Проверка соответствия WCAG на текущем экране	`--verbose`, `--output`
`visual_diff.py`	Сравнение двух скриншотов на предмет визуальных изменений	`--threshold`, `--output`, `--details`
`test_recorder.py`	Автоматическая документация тестов со скриншотами	`--test-name`, `--output`
`app_state_capture.py`	Снимки состояния для отладки (скриншот, иерархия, логи)	`--app-bundle-id`, `--output`, `--log-lines`
`sim_health_check.sh`	Проверка окружения (Xcode, simctl, IDB, Python)	—
`model_inspector.py`	Инспекция моделей Core Data / SwiftData из файлов проекта	`--project-path`, `--raw`, `--show-versions`
`container.py`	Инспекция песочницы приложения: список файлов, чтение файлов (cat), UserDefaults, Core Data, экспорт	`--ls`, `--cat`, `--userdefaults`, `--core-data-path`, `--export`
`hang_watcher.py` (HangBuster)	Запись + суммаризация событий зависаний из `os_log` с прогрессивным раскрытием (режим сессий + сырой NDJSON + устаревший поток); автоперезапуск при обрыве потока, автоматическая очистка при достижении дискового лимита	`--start [--raw-capture --max-size-mb N --no-gzip]`, `--stop`, `--get-details`, `--list-sessions`, `--diff`, `--budget-tokens`, `--auto-sample` (устаревшие: `--watch`, `--since`)
`localization_audit.py`	Аудит каталогов `.xcstrings` на предмет отсутствующих ключей, неиспользуемых ключей и несоответствий плейсхолдеров	`--catalog`, `--source`, `--strict`

Разрешения и окружение

Скрипт	Что делает	Ключевые флаги
`clipboard.py`	Копирование текста в буфер обмена симулятора для тестирования вставки	`--copy`, `--test-name`
`status_bar.py`	Переопределение строки состояния (время, заряд батареи, сеть)	`--preset`, `--time`, `--battery-level`, `--clear`
`push_notification.py`	Отправка смоделированных push-уведомлений	`--bundle-id`, `--title`, `--body`, `--payload`
`privacy_manager.py`	Выдача, отзыв и сброс разрешений приложения (13 сервисов)	`--bundle-id`, `--grant`, `--revoke`, `--reset`

Жизненный цикл устройств

Скрипт	Что делает	Ключевые флаги
`simctl_boot.py`	Запуск симуляторов с проверкой готовности	`--name`, `--wait-ready`, `--timeout`, `--all`, `--type`
`simctl_shutdown.py`	Корректное завершение работы симуляторов	`--name`, `--verify`, `--all`, `--type`
`simctl_create.py`	Создание симуляторов по типу устройства и версии ОС	`--device`, `--runtime`, `--list-devices`
`simctl_delete.py`	Удаление симуляторов с подтверждением безопасности	`--name`, `--yes`, `--all`, `--old`
`simctl_erase.py`	Сброс к заводским настройкам без удаления	`--name`, `--verify`, `--all`, `--booted`

Конфигурация

Каждый рабочий лимит — таймауты, ограничения вывода, интервалы опроса, размер кэша, задержки после действий — можно настроить через переменную окружения IOS_SIM_*. Значения по умолчанию подобраны для локальной разработки на Apple Silicon. Повышайте их на медленных CI-раннерах, в больших монорепозиториях или при проверках доступности на сложных экранах. Понижайте, когда вам нужны более быстрый отказ или более жёсткий бюджет токенов.

Есть универсальный компромисс, который стоит держать в уме:

Более высокие лимиты / более длинные таймауты → меньше ложных сбоев, более полная диагностика, больше токенов, потребляемых ИИ-агентами, и более медленные отказы, когда что-то действительно сломано.
Более низкие лимиты / более короткие таймауты → более быстрая обратная связь, более экономное использование токенов, риск тихой потери ошибок или преждевременных таймаутов на объективно медленных операциях.

Таймауты запуска и жизненного цикла

Сколько времени ждать выполнения операций xcrun simctl.

Переменная	По умолчанию	Компромисс
`IOS_SIM_BOOT_TIMEOUT`	`300` (с)	Ожидание готовности симулятора после `boot`. Ниже → быстрее отказ при сломанных симуляторах. Выше → переживает холодный старт на медленных CI-раннерах (GitHub-hosted macOS может требовать 4–6 минут).
`IOS_SIM_BOOT_SUBPROCESS_TIMEOUT`	`60` (с)	Таймаут самого вызова `simctl boot` (до начала опроса готовности). Редко нуждается в изменении; повышайте только если видите `Boot command timed out` на CI с дефицитом ресурсов.
`IOS_SIM_ERASE_TIMEOUT`	`90` (с)	Ожидание проверки сброса к заводским настройкам. Большие симуляторы (много установленных приложений + данных) могут требовать больше, чем прежние 30 секунд.
`IOS_SIM_POLL_INTERVAL`	`0.5` (с)	Как часто перепроверять состояние boot/erase. Ниже → отзывчивее (больше нагрузки на CPU). Выше → спокойнее на медленном CI, но добавляет задержку в обнаружение „готовности“.
`IOS_SIM_STATE_SUBPROCESS_TIMEOUT`	`15` (с)	Таймаут каждого подпроцесса в `app_state_capture.py`. Повышайте для приложений с очень большими деревьями доступности.

Лимиты вывода сборки и тестов

build_and_test.py по умолчанию возвращает счётчики, а полные детали — через ID xcresult; эти лимиты определяют, что попадает в человекочитаемый/JSON-вывод до того, как вступает в силу прогрессивное раскрытие.

Переменная	По умолчанию	Компромисс
`IOS_SIM_BUILD_SUMMARY_CAP`	`15`	Ошибки / упавшие тесты в текстовом резюме по умолчанию. Ниже → более лаконичный вывод по умолчанию. Выше → меньше необходимости искать xcresult ID для контекста.
`IOS_SIM_BUILD_VERBOSE_CAP`	`100`	Ошибки / предупреждения в режиме `--verbose`. В основном актуально для монорепозиториев или первых сборок с множеством исправимых предупреждений.
`IOS_SIM_BUILD_JSON_CAP`	`50`	Максимум ошибок / упавших тестов в выводе `--json`. Увеличьте для CI-дашбордов, которым нужны исчерпывающие списки.
`IOS_SIM_BUILD_LOG_PREVIEW`	`4000` (символов)	Символов лога сборки, включаемых в вывод по умолчанию. Выше → больше контекста для сбоев, больше токенов.
`IOS_SIM_BUILD_TIMEOUT`	`1800` (с)	Жёсткий лимит на один вызов `xcodebuild build`. Значение по умолчанию 30 минут покрывает большинство чистых сборок крупных приложений; увеличьте для очень больших монорепозиториев, уменьшите для быстрого падения в CI, когда сборки должны занимать секунды. Без этого зависший `xcodebuild` блокировался бы навсегда.
`IOS_SIM_TEST_TIMEOUT`	`2700` (с)	Жёсткий лимит для `xcodebuild test`. Тесты могут занимать значительно больше времени, чем сборки (по умолчанию 45 минут) из-за загрузки симулятора и задержек анимации.
`IOS_SIM_INTROSPECT_TIMEOUT`	`60` (с)	Таймаут для вызовов интроспекции `xcodebuild -list` и `xcrun simctl list`. Обычно они должны завершаться менее чем за 1 секунду; 60 секунд позволяет поймать зависания тулчейна Xcode, не нарушая холодный запуск.

Вывод монитора логов

log_monitor.py агрегирует вывод os_log; эти лимиты формируют как текстовое резюме, так и структурированный JSON.

Переменная	По умолчанию	Компромисс
`IOS_SIM_LOG_TEXT_SUMMARY`	`15`	Ошибки / предупреждения, показываемые в текстовом резюме. Значения по умолчанию достаточно для большинства задач отладки без затопления вывода терминала.
`IOS_SIM_LOG_LINE_MAX`	`300` (символов)	Построчная обрезка. Сообщения о крахах с полным Swift-манглированием символов могут превышать 200 символов; увеличьте, если видите «…», обрезающее важную часть.
`IOS_SIM_LOG_TAIL`	`200` (строк)	Последние строки лога, показываемые в подробном режиме и в JSON `sample_logs`. Также используется выдержкой лога xcode. Меньше — более компактный контекст, больше — более содержательный разбор после сбоя.
`IOS_SIM_LOG_JSON_CAP`	`100`	Максимум ошибок / предупреждений в JSON-выводе. Увеличьте, если передаёте данные в дашборд, которому нужна полная картина.
`IOS_SIM_HANG_PREDICATE`	(по умолчанию)	Переопределяет предикат `os_log`, используемый `hang_watcher.py`. Предикат по умолчанию ловит завершения от watchdog RunningBoard, явные сообщения «Hang detected» и аннотации зависаний главного потока. События зависаний исходят от системных демонов (RunningBoard, SpringBoard, watchdog), а не от процесса целевого приложения, поэтому предикат намеренно остаётся глобальным для симулятора. `--bundle-id` применяется постфактум к полезной нагрузке события после парсинга, но никогда не добавляется через AND в сам предикат.
`IOS_SIM_HANG_MIN_MS`	`250`	Порог HangBuster: события короче этой длительности никогда не попадают на диск.
`IOS_SIM_HANG_SESSION_TTL_HOURS`	`24`	Возраст очистки сессий HangBuster. Очистка выполняется при каждом `--start`.
`IOS_SIM_HANG_DEFAULT_TOP_N`	`3`	Кластеры top-N по умолчанию в L1-выводе `--stop`.
`IOS_SIM_HANG_BUDGET_TOKENS`	(не задано)	Бюджет токенов по умолчанию для `--stop` (подбирает L0/L1/L2, чтобы уложиться).
`IOS_SIM_HANG_MAX_RESTARTS`	`3`	Рабочий процесс HangBuster: ограниченное число попыток перезапуска `log stream` при EOF/гибели подпроцесса, прежде чем сессия помечается как `crashed`. Установите `0`, чтобы отключить автоперезапуск.
`IOS_SIM_HANG_TOTAL_CAP_MB`	`100`	Совокупный дисковый лимит HangBuster. Когда суммарное состояние сессий превышает это значение при `--start`, первыми удаляются самые старые сессии. Установите `0`, чтобы отключить.

Навигация по UI и сопоставление экранов

Эти параметры определяют, что видят ИИ-агенты при исследовании экрана. Это самый большой прямой рычаг влияния на потребление токенов за шаг навигации.

Переменная	По умолчанию	Компромисс
`IOS_SIM_MAX_ELEMENTS`	`25`	Нажимаемые элементы, перечисляемые `navigator.py`. Значения по умолчанию достаточно для большинства экранов; увеличьте до `100+` для плотных экранов в стиле «Настроек» или рабочих процессов аудита. Высокое влияние на токены при больших значениях.
`IOS_SIM_SCREEN_BUTTONS_PREVIEW`	`15`	Названия кнопок в резюме `screen_mapper.py`.
`IOS_SIM_SCREEN_SECTION_ITEMS`	`10`	Элементы на секцию в резюме `screen_mapper.py`.
`IOS_SIM_APPS_PREVIEW`	`30`	Установленные приложения, перечисляемые `app_launcher.py` до усечения.
`IOS_SIM_TAP_SETTLE_MS`	`500` (мс)	Задержка после нажатия перед чтением нового состояния. Меньше → быстрее навигация на отзывчивых приложениях. Больше → безопаснее на приложениях с тяжёлыми анимациями или асинхронной загрузкой; линейно увеличивает время выполнения end-to-end тестов.
`IOS_SIM_RELAUNCH_DELAY_MS`	`1000` (мс)	Задержка между завершением и повторным запуском в `app_launcher.py --restart`. Увеличьте, если при перезапусках предыдущий процесс ещё не успел полностью завершиться.

Аудит доступности

Переменная	По умолчанию	Компромисс
`IOS_SIM_A11Y_TOP_ISSUES`	`10`	Количество главных проблем, выводимых за один аудит. Значение по умолчанию 3 в старых версиях почти всегда было слишком жёстким для реальных приложений. Увеличьте для первичного аудита, уменьшите для проверок регрессий.
`IOS_SIM_A11Y_LABEL_MAX`	`80` (символов)	Максимальное количество символов `AXLabel`, сохраняемых в выводе аудита. Локализованные пользовательские метки часто превышают 30 символов; 80 охватывает почти все.

Кэш прогрессивного раскрытия

ProgressiveCache хранит большие объёмы вывода (результаты сборки, дампы логов), привязанные к коротким идентификаторам, чтобы стандартный вывод оставался минимальным.

Переменная	По умолчанию	Компромисс
`IOS_SIM_CACHE_TTL_HOURS`	`1`	Как долго записи кэша остаются действительными. Ниже → более свежие данные при следующем извлечении, больше повторных запусков. Выше → более быстрые повторные запуски в длинных CI-конвейерах, но риск устаревших результатов, если состояние симулятора изменилось.
`IOS_SIM_CACHE_MAX_ENTRIES`	`500`	Жёсткий лимит; самые старые записи (по mtime) вытесняются при каждом вызове `save()`. Предотвращает неограниченный рост `~/.ios-simulator-skill/cache/` в долго работающих средах. Увеличивайте только если вам часто нужно извлекать записи старше ~500 сохранений.

Примеры

# Slow GitHub Actions macOS runner — give boot up to 10 minutes
IOS_SIM_BOOT_TIMEOUT=600 python scripts/simctl_boot.py --wait-ready

# Monorepo with hundreds of warnings — see them all in verbose mode
IOS_SIM_BUILD_VERBOSE_CAP=500 python scripts/build_and_test.py --verbose

# Complex Settings-style screen — return more tappable elements
IOS_SIM_MAX_ELEMENTS=100 python scripts/navigator.py --list-tappable

# Snappy app — cut tap-settle delay in half for faster E2E runs
IOS_SIM_TAP_SETTLE_MS=250 python scripts/navigator.py --find-text "Login" --tap

# Long CI pipeline — keep cache entries valid for the whole job
IOS_SIM_CACHE_TTL_HOURS=8 python scripts/build_and_test.py --project MyApp.xcodeproj

Также можно экспортировать переменные один раз на всю сессию:

export IOS_SIM_BOOT_TIMEOUT=600
export IOS_SIM_LOG_TAIL=500
export IOS_SIM_MAX_ELEMENTS=50
# … all subsequent scripts honor them

Ошибки разбора откатываются к задокументированному значению по умолчанию с предупреждением в stderr — ни один скрипт не упадёт из-за некорректной переменной окружения.

Оценка

Протестировано с помощью Claude Code evals:

Условие	Доля успешных прохождений
С навыком	100% (3/3)
Без навыка	46% (~1.4/3)

claude evals run evals/evals.json --skill ios-simulator-skill

Лицензия

MIT