lariat
v0.2.0
O Lariat é uma poderosa ferramenta de linha de comando projetada para otimizar a execução de comandos e execução de executáveis em dispositivos Android remotos. Ele alcança isso alavancando a API do DeviceFarmer e a Android Debug Bridge (ADB). Com o Lariat, o processo pesado de conexão manualmente aos dispositivos, empurrando arquivos, executando comandos e recuperação de resultados é simplificado e tornado mais eficiente. É uma solução ideal para automatizar tarefas em oleodutos de integração contínua (IC).
Lariat está disponível no Pypi:
python -m pip install lariatLariat apoia oficialmente o Python 3.8+.
Lariat utiliza um arquivo de configuração JSON. O local padrão para este arquivo de configuração está no diretório .lariat no diretório inicial do usuário ( ~/.lariat/config.json ). O arquivo de configuração é usado para especificar o seguinte:
device_farmer_url : o URL da instância do DeviceFarmer a se conectar.
.json ou .yaml . access_token : seu Token de acesso ao DeviceFarmer.
adb_private_key_path : (Opcional) Caminho para uma chave privada do ADB não padrão. Padrões para ~/.android/adbkey se não for especificado
adb_shell_default_read_timeout_s : (opcional) Tempo limite total padrão (em segundos) para ler dados de um dispositivo. Esse valor pode precisar ser aumentado em relação ao valor padrão de 10s para determinadas operações do 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 as opções de configuração podem ser especificadas na linha de comando para substituir qualquer padrão definido no arquivo de configuração. Por exemplo, a opção Linha de comando --device_farmer_url pode ser usada para substituir o URL do DeviceFarmer definido no arquivo de configuração.
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) As opções --select e --filter usam "nomes de campo" para executar suas respectivas ações. Esses nomes de campo são as teclas JSON, conforme definido pelo DeviceFarmer como parte de sua API REST. Você pode visualizar os campos suportados para a instalação do DeviceFarmer, navegando para o seguinte URL: https://<device_farmer_url>/api/v1/devices/<serial> em que device_farmer_url é o URL para a instalação do Farmer de dispositivo e serial é o número de série de um número de serrial de seus dispositivos. O componente /<serial> pode ser omitido para visualizar todos os campos de todos os dispositivos.
Os nomes de campo suportam a notação de pontos para acessar as teclas aninhadas. Por exemplo, battery.health pode ser usada para acessar a chave health aninhada na battery .
Observe que a especificação de um --filter , juntamente com um --select incluirá automaticamente todos os nomes de campo especificados no filtro no JSON resultante.
abi - Aplicativo de dispositivo Interface binária (por exemplo, armeabi-v7a )manufacturer - fabricante de dispositivosmarketName - nome de marketing de dispositivosmodel - Nome do modelo de dispositivoprovider.name - Provedor de STF que hospeda este dispositivoversion - Versão 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 retorna os resultados para cada dispositivo que atendeu aos critérios de filtragem.
A seguir, é apresentado a saída de amostra para um 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 contém campos diferentes, dependendo da disponibilidade do dispositivo:
Se um dispositivo não estiver disponível , o resultado terá um único campo:
reason : especifica por que o dispositivo não estava disponível para uso, como está em uso atualmente, não presente no intervalo, etc.Se um dispositivo estiver disponível e uma operação foi realizada nele, o resultado incluirá dois campos:
output : contém a saída do shell adb do comando executado ou detalhes sobre a ação executada.exitcode : O código de retorno do comando ou ação executado no dispositivo.Lembre -se de que um dispositivo terá um campo de 'razão' (se não estivesse disponível) ou 'saída' e 'saitcode' campos
Por conveniência, uma imagem oficial do Docker Lariat está disponível.
Para usar a imagem do Docker, basta executar
docker run --rm -v ~ /.android:/root/.android:ro -v ~ /.lariat:/root/.lariat:ro ghcr.io/zetier/lariat:latest -c ' echo hello 'Este comando Docker Run cria e executa um contêiner do Docker baseado na imagem ghcr.io/zetier/lariat:latest. Ele executa as seguintes ações:
Cria uma montagem de volume somente leitura para o diretório .android na máquina host, que contém teclas de ADB, no diretório /root/.android dentro do contêiner.
Cria uma montagem de volume somente leitura para o diretório .lariat na máquina host, que contém o arquivo de configuração lariat, no diretório /root/.lariat dentro do contêiner.
O sinalizador - -RM garante que o contêiner seja removido automaticamente após a saída.
Dentro do contêiner, o comando lariat -c 'echo hello' é executado, que imprime "Hello" como a saída em todos os dispositivos bloqueáveis em sua faixa de dispositivos.
Observe que, se as teclas do ADB e o arquivo de configuração estiverem localizados em diferentes diretórios na máquina host, pode ser necessário modificar o comando do Docker Run de acordo para fornecer os caminhos corretos para a montagem do volume.
Lariat foi projetado para uma integração simples em pipelines de IC. Abaixo está um exemplo de um trabalho do GitLab que testa um binário construído no pipeline em uma linha 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
A Lariat bloqueará os dispositivos antes de executar qualquer operações para garantir acesso exclusivo. Após a conclusão das operações, os dispositivos serão desbloqueados.
Certifique -se de fornecer o caminho correto para o arquivo de chave privada do ADB via ~/.lariat/config.json se for diferente do local padrão ( ~/.android/adbkey )
Por padrão, Lariat enumerará todo Dispositivo na faixa do DeviceFarmer, incluindo aqueles que não present ou ready . Você pode modificar isso conforme necessário, especificando --filter ready=true present=true se necessário.
Nota: Lariat é desenvolvido e testado regularmente com o Ubuntu 18.04 com o Python 3.8. Outras distribuições e versões podem funcionar, mas atualmente não são testadas.
Clone o repositório
Instale dependências junto com o pacote 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 .Crie um arquivo de configuração
As contribuições são bem -vindas! Se você encontrar algum problema ou ter sugestões de melhorias, abra um problema ou envie uma solicitação de tração.
Este projeto está licenciado sob a licença GPLV2.
