simctl: управление симуляторами Apple через терминал

Всем привет! Меня зовут Паша Лесюк, я работаю мобильным тестировщиком в компании Циан. В этой статье я расскажу о возможностях управления яблочными симуляторами из командной строки.

simctl — утилита командной строки для взаимодействия с симуляторами. Она очень похожа на ADB для Android, устанавливается вместе со средой разработки Xcode и используется вместе с xcrun (Xcode-раннер командной строки). Двоичный файл программы можно найти по пути:

/Applications/Xcode.app/Contents/Developer/usr/bin/simctl

Работа с объектами устройств

Просмотр списка доступных команд и информации по ним

Команда simctl без подкоманд выводит в консоль список всех доступных подкоманд (далее будет использоваться термин «команда»).

$ xcrun simctl

Для просмотра подробной информации по команде нужно использовать команду help с названием искомой команды.

$ xcrun simctl help list

Просмотр списка доступных устройств, сред выполнения, устройств и пар устройств

Команда list выводит список всех установленных устройств и окружений. Рядом с каждым устройством будет отображен UDID (уникальный идентификатор устройства), который можно прокидывать в некоторые подкоманды simctl.

$ xcrun simctl list

Пример UDID:

4599F586-F482-4E9C-92A7-8AC4EF348BD9

Список можно фильтровать по заголовкам: devices, devicetypes, runtimes, pairs.

$ xcrun simctl list devices
== Devices ==
-- iOS 11.0 --
    iPhone 7 (422566D6-AD4C-40E5-AC64-233043A00814) (Shutdown)
-- iOS 13.4 --
    iPhone 8 (CB87B315-F01A-41AA-9C85-6FE24E5A66B9) (Shutdown)

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

$ xcrun simctl list devices available

Примером поискового запроса может служить выборка по устройствам c экраном 12.9 дюймов.

$ xcrun simctl list devicetypes 12.9
== Device Types ==
iPad Pro (12.9-inch) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro)
iPad Pro (12.9-inch) (2nd generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro--12-9-inch---2nd-generation-)
iPad Pro (12.9-inch) (3rd generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro--12-9-inch---3rd-generation-)
iPad Pro (12.9-inch) (4th generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro--12-9-inch---4th-generation-)

Можно вывести более подробную информацию списка c помощью параметра -v.

$ xcrun simctl list -v devices
== Devices ==
-- iOS 11.0 (15A8401) [/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 11.0.simruntime] --
    iPhone 7 (7B68E927-161C-440C-AABE-654CD96E8694) (Shutdown)
-- iOS 13.3 (17C45) [/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS.simruntime] --
    iPhone 8 (F3909F6E-E227-4BD7-939F-D3D05B1B8AAD) (Shutdown)

Можно вывести информацию в формате JSON с помощью параметра -j или --json.

$ xcrun simctl list -j -v devices
{
    "devices" : {
    "com.apple.CoreSimulator.SimRuntime.iOS-13-3" : [
        {
        "dataPath" : "/Users/pavel/Library/Developer/CoreSimulator/Devices/9EA47EEB-F19F-44EE-9854-EA06BEB8FBD1/data",
        "logPath" : "/Users/pavel/Library/Logs/CoreSimulator/9EA47EEB-F19F-44EE-9854-EA06BEB8FBD1",
        "udid" : "9EA47EEB-F19F-44EE-9854-EA06BEB8FBD1",
        "isAvailable" : true,
        "deviceTypeIdentifier" : "com.apple.CoreSimulator.SimDeviceType.iPhone-7-Plus",
        "state" : "Shutdown",
        "name" : "iPhone-7-Plus"
        },
        {
        "dataPath" : "/Users/pavel/Library/Developer/CoreSimulator/Devices/F3909F6E-E227-4BD7-939F-D3D05B1B8AAD/data",
        "logPath" : "/Users/pavel/Library/Logs/CoreSimulator/F3909F6E-E227-4BD7-939F-D3D05B1B8AAD",
        "udid" : "F3909F6E-E227-4BD7-939F-D3D05B1B8AAD",
        "isAvailable" : true,
        "deviceTypeIdentifier" : "com.apple.CoreSimulator.SimDeviceType.iPhone-8",
        "state" : "Shutdown",
        "name" : "iPhone 8"
        }
    ],
    ...

Создание нового устройства

Для создания нового симулятора используется команда create, после которой указываются имя устройства, его тип и среда (эти данные есть в выводе команды list). После выполнения команды отобразится UDID созданного симулятора.

$ xcrun simctl create iPhone-7-Plus com.apple.CoreSimulator.SimDeviceType.iPhone-7-Plus com.apple.CoreSimulator.SimRuntime.iOS-13-4
9EA47EEB-F19F-44EE-9854-EA06BEB8FBD1

Запуск устройства

Команда boot запускает устройство с указанным UDID, делая его доступным для взаимодействия.

$ xcrun simctl boot CB87B315-F01A-41AA-9C85-6FE24E5A66B9

️После запуска устройства можно передавать команду booted вместо UDID. Если запущено несколько устройств, то simctl выберет одно из них.

Чтобы увидеть симулятор в действии нужно запустить приложение «Simulator».

$ open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/

Апгрейд устройства

Команда upgrade позволяет повысить версию среды устройства до необходимой.

$ xcrun simctl upgrade 422566D6-AD4C-40E5-AC64-233043A00814 com.apple.CoreSimulator.SimRuntime.iOS-13-4

Клонирование устройства

Команда clone позволяет клонировать существующее устройство, копируя его тип и среду.

$ xcrun simctl clone booted NewPhone

Очистка данных и настроек устройства

Для сброса симулятора к настройкам по умолчанию используется команда erase. Перед очисткой симулятора его нужно выключить, иначе возникнет ошибка.

$ xcrun simctl erase booted

Если нужно сбросить данные всех симуляторов, то нужно использовать команду erase all.

$ xcrun simctl erase all

Переименование устройства

Изменить имя устройства можно с помощью команды rename.

$ xcrun simctl rename booted MyiPhone

Вывод переменных среды устройства

Команда getenv позволяет выводить значения переменных среды устройства. Например, встроенная переменная симулятора SIMULATOR_SHARED_RESOURCES_DIRECTORY указывает на путь, где хранятся данные симулятора.

$ xcrun simctl getenv booted SIMULATOR_SHARED_RESOURCES_DIRECTORY
/Users/pavel/Library/Developer/CoreSimulator/Devices/F3909F6E-E227-4BD7-939F-D3D05B1B8AAD/data

Проверка состояния загрузки устройства

Команда bootstatus позволяет убедиться в том, что устройство загружено и готово к работе. Имеет три необязательных ключа:

• -b — загружает указанный симулятор, если он не загружен.
• -d — отображает информацию о миграции данных.
• -c — постоянно отслеживает состояние загрузки и выключения.

$ xcrun simctl bootstatus booted
$ xcrun simctl bootstatus booted -c

Выключение устройства

Когда работа с симулятором закончена, можно выключить его, используя команду shutdown.

$ xcrun simctl shutdown booted

Для выключения всех симуляторов используется команда shutdown all.

$ xcrun simctl shutdown all

Удаление устройств

В ходе работы с симуляторами может накапливаться большое количество старых устройств, многие из которых могут быть недоступны для последних версий iOS. Для их удаления используется команда delete unavailable.

$ xcrun simctl delete unavailable

Для удаления конкретного симулятора используется команда delete.

$ xcrun simctl delete booted

Для удаления всех устройств используется команда delete all.

$ xcrun simctl delete all

Работа с контентом устройств

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

Можно просто использовать шорткат ⌘⇧4, навести курсором на окно симулятора, нажать пробел и сделать скриншот. Но тогда на скриншоте кроме самого экрана будут видны рамки симулятора.

Для снятия скриншота только экрана используется команда io в связке со screenshot. Можно сохранять изображения в формате .png, .tiff, .bmp, .gif и .jpeg.

$ xcrun simctl io booted screenshot ~/Pictures/app-screenshot.png

Аналогично, можно просто использовать шорткат ⌘S в открытом приложении «Simulator», скриншот окна сохранится на рабочем столе.

Также можно использовать команду io в связке с recordVideo для записи видео взаимодействия с экраном симулятора. Можно сохранять видео в формате .mov, .h264, .mp4 и .fmp4.

$ xcrun simctl io booted recordVideo ~/Movies/app-preview.mp4

Для завершения записи нужно нажать ⌃C в окне терминала.

Добавление медиа на устройство

Команда addmedia используется для добавления фото или видео на симулятор.

$ xcrun simctl addmedia booted ~/Pictures/test.png
$ xcrun simctl addmedia booted ~/Pictures/test.gif
$ xcrun simctl addmedia booted ~/Pictures/test.mp4

Также можно просто перетащить файл из Finder в окно симулятора.

Открытие URL на устройстве

Команда openurl открывает указанный URL на симуляторе.

$ xcrun simctl openurl booted "https://www.google.com/"

Также может использоваться кастомная схема, ассоциированная с нативным приложением.

$ xcrun simctl openurl booted maps://

Управление сертификатами устройства

Команда keychain позволяет добавлять сертификаты в доверенное корневое хранилище или keychain, а также сбрасывать keychain.

$ xcrun simctl keychain booted add-root-cert ~/my-selfsigned.cer
$ xcrun simctl keychain booted add-cert ~/my-selfsigned.cer
$ xcrun simctl keychain booted reset

Установка приложения на устройство

Можно легко установить приложение на симулятор если известен путь к файлу .app. Для этого используется команда install.

$ xcrun simctl install booted ~/Циан.app

Также можно просто перетащить приложение из Finder в окно симулятора.

Перечень opensource-приложений для iOS можно найти тут.

Запуск приложения на устройстве

Запуск приложения осуществляется с помощью команды launch и указанием bundle ID.

$ xcrun simctl launch booted ru.cian.mobile

Как узнать bundle ID описано тут.

Предоставление, отзыв и сброс разрешений приложения

Команда privacy может предоставлять, отзывать и сбрасывать разрешения приложения.

$ xcrun simctl privacy <device> <action> <service> <bundle ID>

Значения action (действия) могут быть следующие:

• grant — предоставляет доступ к сервису. Неободим bundle ID.
• revoke — запрещает доступ к сервису. Необходим bundle ID.
• reset — сбрасывает доступ к сервису. bundle ID опционален.

Значения service (службы) могут быть следующие:

• all — применяет действие ко всем службам.
• calendar — предоставляеть доступ к календарю.
• contacts-limited — предоставляет доступ к основной контактной информации.
• contacts — предоставляет полный доступ к контактной информации.
• location — предоставляет доступ к службам определения местоположения при использовании приложения.
• location-always — предоставляет доступ к службам определения местоположения в любое время.
• photos-add — предоставляет доступ на добавление фотографий в библиотеку фотографий.
• photos — предоставляет полный доступ к библиотеке фотографий.
• media-library — предоставляет доступ к медиа-библиотеке.
• microphone — предоставляет доступ к микрофону.
• motion — предоставляет доступ к фитнес-данным.
• reminders — предоставляет доступ к напоминаниям.
• siri — предоставляет возможность использовать приложение вместе с Siri.

Пример использования:

$ xcrun simctl privacy booted grant photos ru.cian.mobile
$ xcrun simctl privacy booted grant location ru.cian.mobile
$ xcrun simctl privacy booted revoke all ru.cian.mobile

На данный момент не все сервисы доступны для настройки. Отсутствуют уведомления, здоровье, Bluetooth и Face ID.

Отображение информации о приложении

Команда appinfo выводит информацию о приложении.

$ xcrun simctl appinfo booted ru.cian.mobile

Формат отображения информации следующий:

{
    ApplicationType = User;
    Bundle = <PATH_TO_APP_FILE>;
    BundleContainer = <PATH_TO_APP_FILE_FOLDER>;
    CFBundleDisplayName = "Циан";
    CFBundleExecutable = "Циан";
    CFBundleIdentifier = "ru.cian.mobile";
    CFBundleName = "Циан";
    CFBundleVersion = 1;
    DataContainer = <PATH_TO_DATA_FOLDER>;
    GroupContainers =     {
        <GROUP_CONTAINER_NAME> = <PATH_TO_GROUP_CONTAINER_FOLDER>;
    };
    Path = <PATH_TO_APP_FILE>;
    SBAppTags =     (
    );
}

Отображение пути к контейнерам установленного приложения

Можно вывести путь к контейнерам приложения через команду get_app_container с указанием bundle ID. У команды есть несколько опций для указания типа контейнера:

• app указывает на расположение самого приложения и используется по умолчанию.

$ xcrun simctl get_app_container booted ru.cian.mobile
$ xcrun simctl get_app_container booted ru.cian.mobile app

• data указывает на расположение данных приложения.

$ xcrun simctl get_app_container booted ru.cian.mobile data

• groups указывает на расположение группы приложений. Если групп несколько, то нужно использовать имя искомой группы.

$ xcrun simctl get_app_container booted ru.cian.mobile groups
$ xcrun simctl get_app_container booted ru.cian.mobile group.ru.cian.mobile.widget

Закрытие приложения на устройстве

Закрытие приложения осуществляется с помощью команды terminate и указанием bundle ID.

$ xcrun simctl launch terminate ru.cian.mobile

Удаление приложения с устройства

Можно удалить приложение с симулятора с помощью команды uninstall, используя bundle ID.

$ xcrun simctl uninstall booted ru.cian.mobile

Симуляция отправки пуш-уведомления

Для отправки пуша нужно подготовить файл, который должен содержать структуру в формате JSON и сохранить его с расширением .apns (Apple Push Notification service):

{
    "aps": {
        "alert": {
            "title": "Tester on Steroids",
            "body": "About mobile apps testing"
        },
        "badge": 3,
        "sound": "default"
    }
}

Затем нужно дать разрешение на отправку приложению уведомлений. После этого нужно выполнить команду push с указанием устройства, bundle ID и пути до файла .apns.

$ xcrun simctl push booted ru.cian.mobile ~/Documents/mocks/push.apns

Если добавить в файл параметр "Simulator Target Bundle", то необходимость указывать каждый раз bundle ID отпадает.

{
    "aps": {
        "alert": {
            "title": "Tester on Steroids",
            "body": "About mobile apps testing"
        },
        "badge": 3,
        "sound": "default"
    },
    "Simulator Target Bundle": "ru.cian.mobile"
}

$ xcrun simctl push booted ~/Documents/mocks/push.apns

Также, если указан параметр "Simulator Target Bundle", то файл можно просто перетащить в окно симулятора.

Изменение и очистка статус-бара устройства

У команды status_bar есть три подкоманды:

• override принимает параметры для элементов статус-бара и меняет их в зависимости от значений.

$ xcrun simctl status_bar booted override --time 10:30 --dataNetwork wifi --wifiMode active --wifiBars 2 --cellularMode active --cellularBars 3 --operatorName @tester_on_steroids --batteryState charging --batteryLevel 75

• list выводит значения перезаписанных параметров.

$ simctl status_bar booted list
Current Status Bar Overrides:
=============================
Time: 10:30
DataNetworkType: 1
Cell Mode: 3, Cell Bars: 3
Operator Name: @tester_on_steroids
Battery State: 1, Battery Level: 75, Not Charging: 1

• clear очищает перезаписанный статуc-бар.

$ simctl status_bar booted clear

Установка темной или светлой темы

Данная опция доступна для симуляторов с iOS от 13.0 и выше. C помощью команды ui appearance можно поменять тему устройства на темную или светлую.

$ xcrun simctl ui booted appearance dark
$ xcrun simctl ui booted appearance light

Работа с логами и внутренними механизмами устройств

Выполнение указанной операции на устройстве

Команда spawn создает указанный процесс на симуляторе.

$ xcrun simctl spawn booted defaults write ru.cian.mobile ResetDatabase -bool YES

Здесь используется интерфейс defaults, в котором флагу ResetDatabase устанавливается значение YES. Это удобный способ менять пользовательские настройки до запуска приложения.

Включение и отключение подробного логирования на устройстве

Команда logverbose позволяет включать и отключать подробное логирование на устройстве. Для того, чтобы изменения вступили в силу, нужно перезапустить симулятор.

$ simctl logverbose booted enable
$ simctl logverbose booted disable

Отображение логов с устройства

В iOS существует пять уровней логов:

1. Default. Используется для сбора информации о вещах, которые могут привести к сбою.
2. Info. Полезная, но необязательная информация для устранения ошибок.
3. Debug. Информация, которая может быть полезна во время разработки или устранения конкретной проблемы. Отслеживание debug-логов предназначено для использования на стадии разработки, а не на стадии эксплуатации программы конечными пользователями.
4. Error. Используется для сбора информации об ошибках процесса.
5. Fault. Используется для сбора информации об ошибках системного уровня или мульти-процессов.

Для того, чтобы просмотреть вывод логов с симулятора в командной строке, необходимо выполнить следующую команду:

$ xcrun simctl spawn booted log stream

По умолчанию вывод логов будет включать в себя уровни default, error и fault. Для использования уровней info и debug нужно использовать аргумент --level. --level=info будет отображать уровни по умолчанию, а так же info. --level=debug будет отображать уровни по умолчанию, а так же info и debug.

$ xcrun simctl spawn booted log stream --level=info
$ xcrun simctl spawn booted log stream --level=debug

Также можно фильтровать логи. Например, по конкретному приложению или по типу ивентов и сообщений.

$ xcrun simctl spawn booted log stream --predicate 'processImagePath endswith "Циан"'
$ xcrun simctl spawn booted log stream --predicate 'eventMessage contains "error" and messageType == info'

Чтобы выключить вывод логов нужно нажать ⌃C в окне терминала.

C помощью операции log collect можно сделать дамп журнала логов.

$ xcrun simctl spawn booted log collect

Сбор диагностической информации и логов

С помощью команды diagnose можно сгенерировать подробный журнал всего, что происходило в сессии приложения «Simulator».

$ xcrun simctl diagnose

Журнал будет включать в себя:

• системные логи,
• логи симулятора,
• устройства и окружения,
• настройки устройств,
• дополнительную информацию.

В журнале будет содержаться конфиденциальная информация, поэтому с этими данными нужно быть осторожным.

После генерации журнала будет открыта папка с архивом, содержащим всю информацию.

Заключение

В заключение хотелось бы поделиться еще парой полезных команд для работы с симуляторами.

Включение и отключение полноэкранного режима окна симулятора

Позволяет использовать окно симулятора в полноэкранном режиме macOS. Например, можно открыть отдельный рабочий стол с Xcode и симулятором.

defaults write com.apple.iphonesimulator AllowFullscreenMode 1
defaults write com.apple.iphonesimulator AllowFullscreenMode 0

Включение и отключение отображения нажатий на устройстве

Отображает тапы на симуляторе. Удобно при записи видео.

defaults write com.apple.iphonesimulator ShowSingleTouches 1
defaults write com.apple.iphonesimulator ShowSingleTouches 0

---

P. S.
Если вам интересна тема тестирования, то приглашаю вас подписаться на мой блог в телеграме.

Автор: Павел Лесюк

Источник