lariat
v0.2.0
Lariat es una poderosa herramienta de línea de comandos diseñada para optimizar la ejecución de comandos y ejecutar ejecutables en dispositivos Android remotos. Logra esto aprovechando la API de DeviceFarmer y el puente de depuración de Android (ADB). Con Lariat, el proceso engorroso de conectarse manualmente a dispositivos, presionar archivos, ejecutar comandos y recuperar resultados se simplifica y se hace más eficiente. Es una solución ideal para automatizar tareas en tuberías de integración continua (IC).
Lariat está disponible en Pypi:
python -m pip install lariatLariat apoya oficialmente a Python 3.8+.
Lariat utiliza un archivo de configuración JSON. La ubicación predeterminada para este archivo de configuración está en el directorio .lariat dentro del directorio de inicio del usuario ( ~/.lariat/config.json ). El archivo de configuración se utiliza para especificar lo siguiente:
device_farmer_url : la URL de la instancia de DeviceFarmer para conectarse.
.json o .yaml . access_token : su token de acceso de Farmer Device.
adb_private_key_path : (Opcional) Ruta a una clave privada ADB no predeterminada. El valor predeterminado es ~/.android/adbkey si no se especifica
adb_shell_default_read_timeout_s : (Opcional) Tiempo de espera total predeterminado (en segundos) para leer datos de un dispositivo. Es posible que este valor deba aumentarse del valor predeterminado de 10s para ciertas operaciones del dispositivo.
{
"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
} Todas las opciones de configuración se pueden especificar en la línea de comando para anular cualquier valor predeterminado establecido en el archivo de configuración. Por ejemplo, la opción Línea de comando --device_farmer_url se puede usar para anular el conjunto de URL de Farmer Device en el archivo de configuración.
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) Las opciones --select y --filter usan "nombres de campo" para realizar sus respectivas acciones. Estos nombres de campo son las teclas JSON según lo definido por DeviceFarmer como parte de su API REST. Puede ver los campos compatibles para su instalación de DeviceFarmer navegando a la siguiente URL: https://<device_farmer_url>/api/v1/devices/<serial> donde device_farmer_url es la URL a su instalación y serial de dispositivos. de sus dispositivos. El componente /<serial> se puede omitir para ver todos los campos de todos los dispositivos.
Los nombres de campo admiten notación de puntos para acceder a las claves anidadas. Por ejemplo, battery.health . La salud se puede usar para acceder a la clave health anidada dentro de battery .
Tenga en cuenta que especificar un --filter junto con un --select incluirá automáticamente cualquier nombre de campo especificado en el filtro en el JSON resultante.
abi - Interfaz binaria de aplicación del dispositivo (por ejemplo, armeabi-v7a )manufacturer - Fabricante de dispositivosmarketName - Nombre de marketing de dispositivosmodel - Dispositivo Nombre del modeloprovider.name - Provider STF que aloja este dispositivoversion - Versión de Androidlariat --get-devices--get-devices : lariat --get-devices --select serial model statuslariat --get-devices --filter manufacturer=SAMSUNG sdk=2[5-7]lariat --get-devices --filter provider.name=my.devicefarmer.comlariat --exec-file path/to/hellolariat --command " echo hello " --filter abi=arm64-v8alariat --push-files path/to/filesLariat devuelve los resultados para cada dispositivo que cumplió con los criterios de filtrado.
La siguiente es la salida de muestra para un comando 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 " ,
}Cada resultado contiene diferentes campos dependiendo de la disponibilidad del dispositivo:
Si un dispositivo no está disponible , el resultado tendrá un solo campo:
reason : Especifica por qué el dispositivo no estaba disponible para su uso, como estar actualmente en uso, no presente en la gama, etc.Si hay un dispositivo disponible y se realizó una operación, el resultado incluirá dos campos:
output : contiene la salida de shell ADB del comando ejecutado, o detalles sobre la acción realizada.exitcode : el código de retorno del comando o acción ejecutado en el dispositivo.Recuerde que un dispositivo tendrá un campo de 'razón' (si no estaba disponible) o los campos de 'salida' y 'salida de código'
Por conveniencia, una imagen oficial de Lariat Docker está disponible.
Para usar la imagen de Docker, simplemente ejecute
docker run --rm -v ~ /.android:/root/.android:ro -v ~ /.lariat:/root/.lariat:ro ghcr.io/zetier/lariat:latest -c ' echo hello 'Este comando Docker Ejecutar crea y ejecuta un contenedor Docker basado en la imagen GHCR.io/zetier/Lariat:Latest. Realiza las siguientes acciones:
Crea un montaje de volumen de solo lectura para el directorio .Android en la máquina host, que contiene claves ADB, al directorio /Root/.Android dentro del contenedor.
Crea un montaje de volumen de solo lectura para el directorio .Lariat en la máquina host, que contiene el archivo de configuración de Lariat, al directorio /.
La bandera - -RM asegura que el contenedor se elimine automáticamente después de que salga.
Dentro del contenedor, se ejecuta el comando lariat -c 'echo hello' , que imprime "Hello" como la salida en cada dispositivo bloqueable en su rango de Farmer Device.
Tenga en cuenta que si sus claves y archivo de configuración ADB están ubicados en diferentes directorios en la máquina host, es posible que deba modificar el comando Docker Ejecutar en consecuencia para proporcionar las rutas correctas para el montaje de volumen.
Lariat fue diseñado para una simple integración en tuberías de CI. A continuación se muestra un ejemplo de un trabajo de gitlab que prueba un binario construido en la tubería en una gama de farmer de dispositivos:
.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 bloqueará los dispositivos antes de realizar cualquier operación para garantizar un acceso exclusivo. Después de que se hayan completado las operaciones, los dispositivos se desbloquearán.
Asegúrese de proporcionar la ruta correcta al archivo de clave privada ADB a través de ~/.lariat/config.json si es diferente de la ubicación predeterminada ( ~/.android/adbkey )
Por defecto, Lariat enumerará cada Dispositivo en la gama DeviceFarmer, incluidas las que no present o ready . Puede modificar esto según sea necesario especificando --filter ready=true present=true si es necesario.
Nota: Lariat se desarrolla y se prueba regularmente con Ubuntu 18.04 con Python 3.8. Otras distribuciones y versiones pueden funcionar, pero actualmente no se han probado.
Clonar el repositorio
Instalar dependencias junto con el paquete 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 .Crear un archivo de configuración
¡Las contribuciones son bienvenidas! Si encuentra algún problema o tiene sugerencias de mejoras, abra un problema o envíe una solicitud de extracción.
Este proyecto tiene licencia bajo la licencia GPLV2.
