lariat
v0.2.0
Lariat est un puissant outil de ligne de commande conçu pour rationaliser l'exécution des commandes et l'exécution des exécutables sur des périphériques Android distants. Il y parvient en tirant parti de l'API de DeviceFarmer et du pont Android Debug (ADB). Avec Lariat, le processus lourd de connexion manuellement aux appareils, de poussée de fichiers, de commande et de récupération des résultats est simplifié et rendu plus efficace. Il s'agit d'une solution idéale pour automatiser les tâches dans des pipelines d'intégration continue (IC).
Lariat est disponible sur PYPI:
python -m pip install lariatLariat soutient officiellement Python 3.8+.
Lariat utilise un fichier de configuration JSON. L'emplacement par défaut de ce fichier de configuration se trouve dans le répertoire .lariat dans le répertoire personnel de l'utilisateur ( ~/.lariat/config.json ). Le fichier de configuration est utilisé pour spécifier les éléments suivants:
device_farmer_url : L'URL de l'instance DeviceFarmer à laquelle se connecter.
.json ou .yaml . access_token : votre jeton d'accès de DeviceFarmer.
adb_private_key_path : (facultatif) Chemin vers une clé privée BAD non défaut. Par défaut est ~/.android/adbkey si ce n'est pas spécifié
adb_shell_default_read_timeout_s : (facultatif) Délai total par défaut (en secondes) pour la lecture des données d'un appareil. Cette valeur peut devoir être augmentée à partir de la valeur par défaut de 10s pour certaines opérations de périphérique.
{
"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
} Toutes les options de configuration peuvent être spécifiées sur la ligne de commande pour remplacer tous les défauts définis dans le fichier de configuration. Par exemple, l'option de ligne de commande --device_farmer_url peut être utilisée pour remplacer l'URL de DeviceFarmer dans le fichier de configuration.
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) Les options --select et --filter utilisent toutes deux des «noms de champ» pour effectuer leurs actions respectives. Ces noms de champ sont des touches JSON telles que définies par DeviceFarmer dans le cadre de son API REST. Vous pouvez afficher les champs pris en charge pour votre installation de DeviceFarmer en accédant à l'URL suivante: https://<device_farmer_url>/api/v1/devices/<serial> où device_farmer_url est l'URL à votre instruction de périphérique et serial est le numéro de série de une de vos appareils. Le composant /<serial> peut être omis pour afficher tous les champs de tous les appareils.
Les noms de champ prennent en charge la notation du point pour accéder aux clés imbriquées. Par exemple, battery.health peut être utilisée pour accéder à la clé health imbriquée dans battery .
Notez que la spécification d'un --filter avec un --select inclura automatiquement tous les noms de champ spécifiés dans le filtre dans le JSON résultant.
abi - Interface binaire de l'application de l'appareil (par armeabi-v7a .manufacturer - fabricant d'appareilsmarketName - Nom de marketing d'appareilmodel - Nom du modèle de périphériqueprovider.name - fournisseur STF hébergeant cet appareilversion - Version 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 renvoie les résultats pour chaque appareil qui répondait aux critères de filtrage.
Ce qui suit est une sortie d'échantillonnage pour une commande 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 " ,
}Chaque résultat contient différents champs en fonction de la disponibilité de l'appareil:
Si un appareil n'est pas disponible , le résultat aura un seul champ:
reason : Spécifie pourquoi l'appareil n'était pas disponible pour une utilisation, tel qu'il est actuellement utilisé, pas présent sur la plage, etc.Si un appareil est disponible et qu'une opération a été effectuée dessus, le résultat comprendra deux champs:
output : contient la sortie du shell ADB de la commande exécutée ou des détails sur l'action effectuée.exitcode : le code de retour de la commande ou de l'action exécutée sur l'appareil.N'oubliez pas qu'un appareil aura soit un champ «raison» (s'il n'était pas disponible) ou des champs «sortie» et «eXitcode»
Pour plus de commodité, une image officielle de latiat docker est disponible.
Pour utiliser l'image Docker, exécutez simplement
docker run --rm -v ~ /.android:/root/.android:ro -v ~ /.lariat:/root/.lariat:ro ghcr.io/zetier/lariat:latest -c ' echo hello 'Cette commande docker run crée et exécute un conteneur docker basé sur l'image ghcr.io/zetier/lariat:llast. Il effectue les actions suivantes:
Crée un support de volume en lecture seule pour le répertoire .Android sur la machine hôte, qui contient des touches ADB, vers le répertoire /root/.android à l'intérieur du conteneur.
Crée un support de volume en lecture seule pour le répertoire .lariat sur la machine hôte, qui contient le fichier de configuration de Lariat, vers le répertoire /root/.lariat à l'intérieur du conteneur.
L'indicateur - RM garantit que le conteneur est automatiquement supprimé après sa sortie.
À l'intérieur du conteneur, la commande lariat -c 'echo hello' est exécutée, qui imprime "bonjour" comme sortie sur chaque périphérique verrouillable de votre gamme de dispositif.
Veuillez noter que si vos touches ADB et votre fichier de configuration se trouvent dans différents répertoires de la machine hôte, vous devrez peut-être modifier la commande Docker Run en conséquence pour fournir les chemins corrects pour le montage de volume.
Lariat a été conçu pour une intégration simple dans les pipelines CI. Vous trouverez ci-dessous un exemple de travail GitLab qui teste un binaire construit dans le pipeline sur une gamme de dispositifs:
.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 verrouillera les appareils avant d'effectuer des opérations pour assurer un accès exclusif. Une fois les opérations terminées, les appareils seront déverrouillés.
Assurez-vous de fournir le chemin correct vers le fichier de clé privée ADB via ~/.lariat/config.json s'il est différent de l'emplacement par défaut ( ~/.android/adbkey )
Par défaut, Lariat va énumérer chaque Appareil sur la gamme de dispositifs Farmer, y compris ceux qui ne sont pas present ou ready . Vous pouvez le modifier selon les besoins en spécifiant --filter ready=true present=true si nécessaire.
Remarque: Lariat est développé et testé régulièrement avec Ubuntu 18.04 avec Python 3.8. D'autres distributions et versions peuvent fonctionner, mais sont actuellement non testées.
Cloner le référentiel
Installez les dépendances avec le package 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 .Créer un fichier de configuration
Les contributions sont les bienvenues! Si vous trouvez des problèmes ou avez des suggestions d'amélioration, veuillez ouvrir un problème ou soumettre une demande de traction.
Ce projet est autorisé sous la licence GPLV2.
