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

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

tsvuu5usrrf3kpyqgwfmdth5yn4.png


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, навести курсором на окно симулятора, нажать пробел и сделать скриншот. Но тогда на скриншоте кроме самого экрана будут видны рамки симулятора.

syclifdvmytcdax0vnpzvax62za.png

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

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


icrv2wceoxfgf4qo53ifiwa03po.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


Значения 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 = ;
    BundleContainer = ;
    CFBundleDisplayName = "Циан";
    CFBundleExecutable = "Циан";
    CFBundleIdentifier = "ru.cian.mobile";
    CFBundleName = "Циан";
    CFBundleVersion = 1;
    DataContainer = ;
    GroupContainers =     {
         = ;
    };
    Path = ;
    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


xy4amw2f9-r8yk9ylbpmx5fk6zi.png

Если добавить в файл параметр "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


jaztlkdmurrumk4rfhcjt0iltd8.png
  • 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.
Если вам интересна тема тестирования, то приглашаю вас подписаться на мой блог в телеграме.

© Habrahabr.ru