Скачать lariat - скачать исходный код lariat

lariat

Другой исходный код

v0.2.0

Скачать

Лариат

Lariat-это мощный инструмент командной строки, предназначенный для оптимизации выполнения команд и запуска исполняемых файлов на удаленных устройствах Android. Это достигает этого, используя API DeviceFarmer и Android Debug Bridge (ADB). С LARIAT громоздкий процесс подключения вручную к устройствам, нажимать файлы, выполнение команд и получение результатов упрощен и стал более эффективным. Это идеальное решение для автоматизации задач в трубопроводах непрерывной интеграции (CI).

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

Python 3.8 или выше
ADB установлен и добавлен на путь системы
DeviceFarmer Access Token
Файл конфигурации JSON, содержащий URL Swagger Spec и Token DeviceFarmer API

Установка

Лариат доступен на PYPI:

python -m pip install lariat

Лариат официально поддерживает Python 3.8+.

Файл конфигурации

LARIAT использует файл конфигурации JSON. Расположение по умолчанию для этого файла конфигурации находится в каталоге .lariat в домашнем каталоге пользователя ( ~/.lariat/config.json ). Файл конфигурации используется для указания следующего:

device_farmer_url : URL -адрес экземпляра DeviceFarmer для подключения.
- Примечание. Lariat добавит стандартную спецификацию API JSON на базовый URL. При использовании пользовательского пути для вашего файла спецификации укажите полный URL -адрес в .json или .yaml .
access_token : ваш токен доступа к устройству.
- Это может быть получено путем входа в пользовательский интерфейс DeviceFarmer и перейти к настройкам-> Keys-> Access Tokens
adb_private_key_path : (Необязательно) Путь к закрытому ключу ADB не деко. По умолчанию ~/.android/adbkey если не указано
adb_shell_default_read_timeout_s : (Необязательно) По умолчанию общий тайм -аут (в секундах) для чтения данных с устройства. Это значение, возможно, должно быть увеличено с значения по умолчанию 10S для определенных операций устройства.

{
   "access_token" : " ef02da4fb3884395af4cf011061a2318ca5e9a04abd04de59c5c99afcce0b7fz " ,
   "device_farmer_url" : " https://my.device-farmer-instance.com/ " ,
   "adb_private_key_path" : " /custom/path/adb.key " ,
   "adb_shell_default_read_timeout_s" : 32.5
}

Все параметры конфигурации могут быть указаны в командной строке, чтобы переопределить любые значения по умолчанию в файле конфигурации. Например, параметр командной строки --device_farmer_url можно использовать для переопределения URL -адреса DeviceFarmer в файле конфигурации.

Использование

usage: lariat [-h] [-g | -e EXEC_FILE | -c COMMAND] [--config CONFIG] [-s SELECT [SELECT ...]] [-f FILTER [FILTER ...]]
                [-p PUSH_FILES]

DeviceFarmer automation tool

optional arguments:
  -h , --help            show this help message and exit
  -g , --get-devices     Enumerate devices on DeviceFarmer instance. Does not execute any commands on devices. Prints JSON results
                        to stdout.
  -e EXEC_FILE, --exec-file EXEC_FILE
                        Push a file and execute it. Pushes to /data/local/tmp/.
  -c COMMAND, --command COMMAND
                        Run a command.
  --config CONFIG       Override the default path to the configuration file. Default:/home/larry.espenshade/.lariat/config.json
  -s SELECT [SELECT ...], --select SELECT [SELECT ...]
                        Select the fields to be returned by --get-devices (-g). If not specified, all fields are returned.
  -f FILTER [FILTER ...], --filter FILTER [FILTER ...]
                        Filter devices via a list of key-value pairs (e.g., sdk=27 manufacturer=SAMSUNG). Non boolean values are
                        regex matched
  -p PUSH_FILES, --push-files PUSH_FILES
                        Specify the path to the file or directory to be pushed to the device. Pushes to /data/local/tmp/.
  -v, --verbose         Increase log level. Can be supplied multiple times to further increase log verbosity (e.g. -vv)

Поля устройства

Параметры --select и --filter используют «имена поля» для выполнения своих соответствующих действий. Эти имена поля являются клавишами JSON, как определено DeviceFarmer как часть его API REST. Вы можете просмотреть поддерживаемые поля для установки DeviceFarmer, перейдя к следующему URL: https://<device_farmer_url>/api/v1/devices/<serial> , где device_farmer_url - URL для установки DeviceFarmer, а serial номер одного из одного из ваших устройств. Компонент /<serial> может быть пропущен для просмотра всех полей всех устройств.

Имена поля поддерживают точечные обозначения для доступа к вложенным ключам. Например, battery.health может использоваться для доступа к вложенному ключу health в battery .

Обратите внимание, что указание --filter вместе с --select автоматически включает любые имена поля, указанные в фильтре в полученном JSON.

Обычно используются поля

abi - Бинарный интерфейс приложения устройства (например, armeabi-v7a )
manufacturer - производитель устройств
marketName - название маркетинга устройств
model - имя модели устройства
provider.name - STF -провайдер размещает это устройство
version - версия Android

Примеры

Перечислять все устройства в экземпляре DeviceFarmer:

lariat --get-devices

Ограничьте поля, возвращаемые- --get-devices :

lariat --get-devices --select serial model status

Фильтрующие устройства на основе конкретных полей и значений (например, все устройства Samsung с уровнем SDK 25-27):

lariat --get-devices --filter manufacturer=SAMSUNG sdk=2[5-7]

Фильтрующие устройства на основе подметки JSON с использованием точечной нотации:

lariat --get-devices --filter provider.name=my.devicefarmer.com

Нажмите локальный файл на устройство и выполните его:

lariat --exec-file path/to/hello

Запустите команду на всех устройствах ARM64:

lariat --command " echo hello " --filter abi=arm64-v8a

Нажмите файлы на устройство:

lariat --push-files path/to/files

Результаты

Лариат возвращает результаты для каждого устройства, которое соответствовало критериям фильтрации.

Ниже приведен пример вывода для команды echo :

lariat --command " echo hello " --filter abi=arm64-v8a

" A12345 " : {
    " output " : " hello " ,
    " exitcode " : 0,
},
" B54321 " : {
    " output " : " hello " ,
    " exitcode " : 0,
},
" C678910 " : {
    " reason " : " Device is currently in use " ,
}

Каждый результат содержит разные поля в зависимости от доступности устройства:

Если устройство недоступно , результат будет иметь одно поле:
- reason : указывает, почему устройство не было доступно для использования, например, оно в настоящее время используется, не присутствует в диапазоне и т. Д.
Если устройство доступно и выполнена операция, результат будет включать в себя два поля:
- output : содержит вывод оболочки ADB выполненной команды или подробности о выполненном действии.
- exitcode : код возврата команды или действия, выполненного на устройстве.

Помните, что устройство будет иметь либо поля «разума» (если оно было недоступно), либо «вывод» и «Extcode»

Docker Image

Для удобства доступно официальное изображение Lariat Docker.

Чтобы использовать изображение Docker, просто запустите

docker run --rm -v ~ /.android:/root/.android:ro -v ~ /.lariat:/root/.lariat:ro ghcr.io/zetier/lariat:latest -c ' echo hello '

Эта команда Docker Run создает и запускает контейнер Docker на основе изображения ghcr.io/zetier/lariat:latest. Он выполняет следующие действия:

Создает монтирование объема только для чтения для каталога .android на хост-машине, который содержит клавиши ADB, в каталог /root/.android внутри контейнера.
Создает монтирование тома только для чтения для каталога .lariat на хост-машине, который содержит файл конфигурации Lariat, в каталог /root/.lariat внутри контейнера.
Флаг - -RM гарантирует, что контейнер автоматически удаляется после его выхода.
Внутри контейнера выполняется команда lariat -c 'echo hello' , которая печатает «Привет» в качестве вывода на каждом блокируемом устройстве на вашем диапазоне DeviceFarmer.

Обратите внимание, что если ваши ключи ADB и файл конфигурации расположены в разных каталогах на хост -машине, вам может потребоваться соответственно изменить команду Docker Run, чтобы предоставить правильные пути для монтажа тома.

CI интеграция

Лариат был разработан для простой интеграции в трубопроводы CI. Ниже приведен пример задания Gitlab, которая проверяет бинарный встроенный в трубопровод на диапазоне Head Farmer:

 .lariat-test :
  image :
    name : ghcr.io/zetier/lariat:latest
    entrypoint : [""]
  stage : test
  before_script :
    # Copy keys and configs from private CI variables
    - mkdir -p ~/.android
    - echo "$CI_ADB_PUB_KEY" > ~/.android/adbkey.pub
    - echo "$CI_ADB_PRI_KEY" > ~/.android/adbkey
    - echo "$CI_FARMHAND_CONFIG" -> ~/.lariat/config.json
  script :
    - lariat --file $BINARY > test_results.json
  artifacts :
    paths :
      - test_results.json

# Assumes a `build-android-binary` job that produces `android_binary`
# as an artifact.
android-range-test :
  extends : .lariat-test
  variables :
    BINARY : android_binary
  needs :
    - build-android-binary

Примечания

Lariat будет блокировать устройства перед выполнением любых операций, чтобы обеспечить эксклюзивный доступ. После завершения операций устройства будут разблокированы.
Обязательно предоставьте правильный путь к файлу частного ключа ADB через ~/.lariat/config.json , если он отличается от местоположения по умолчанию ( ~/.android/adbkey )
По умолчанию, Лариат перечисляет ~~каждый~~ Устройство в диапазоне DeviceFarmer, включая не present или ready . Вы можете изменить это по мере необходимости, указав --filter ready=true present=true если это необходимо.

Установка разработки

ПРИМЕЧАНИЕ: Lariat разрабатывается и регулярно тестируется с Ubuntu 18.04 с Python 3.8. Другие распределения и версии могут работать, но в настоящее время не проверены.

Клонировать репозиторий

Установите зависимости вместе с пакетом Lariat Python

sudo apt-get update
sudo apt-get install python3-venv python3.8-venv -y
python3.8 -m venv venv
source venv/bin/activate
(venv) pip install --upgrade pip
(venv) pip install .

Создать файл конфигурации

Внося

Взносы приветствуются! Если вы найдете какие -либо проблемы или у вас есть предложения по улучшению, откройте проблему или отправьте запрос на привлечение.