Unduh lariat - Unduh Kode Sumber lariat

lariat

Kode sumber lainnya

v0.2.0

Unduh

Tali penjerat ternak

Lariat adalah alat baris perintah yang kuat yang dirancang untuk merampingkan eksekusi perintah dan menjalankan executable pada perangkat Android jarak jauh. Ini mencapai ini dengan memanfaatkan API DeviceFarmer dan Android Debug Bridge (ADB). Dengan Lariat, proses rumit yang menghubungkan secara manual ke perangkat, mendorong file, menjalankan perintah, dan pengambilan hasil disederhanakan dan dibuat lebih efisien. Ini adalah solusi yang ideal untuk mengotomatiskan tugas -tugas dalam pipa integrasi kontinu (CI).

Prasyarat

Python 3.8 atau lebih tinggi
ADB diinstal dan ditambahkan ke jalur sistem
Token akses devicefarmer
File konfigurasi JSON yang berisi URL spec Swagger dan token API DeviceFarmer

Instalasi

Lariat tersedia di PYPI:

python -m pip install lariat

Lariat secara resmi mendukung Python 3.8+.

File konfigurasi

Lariat menggunakan file konfigurasi JSON. Lokasi default untuk file konfigurasi ini ada di direktori .lariat di dalam direktori home pengguna ( ~/.lariat/config.json ). File konfigurasi digunakan untuk menentukan yang berikut:

device_farmer_url : URL instance DeviceFarmer untuk terhubung ke.
- Catatan: Lariat akan menambahkan spesifikasi API JSON standar ke URL dasar. Jika menggunakan jalur khusus untuk file spesifikasi Anda, tentukan URL lengkap yang berakhir di .json atau .yaml .
access_token : Token akses devicefarmer Anda.
- Ini dapat diperoleh dengan masuk ke UI DeviceFarmer Anda, dan pergi ke Pengaturan-> Keys-> Akses Token
adb_private_key_path : (Opsional) Jalur ke kunci privat ADB non-default. Default ke ~/.android/adbkey jika tidak ditentukan
adb_shell_default_read_timeout_s : (opsional) Total timeout default (dalam detik) untuk membaca data dari perangkat. Nilai ini mungkin perlu ditingkatkan dari nilai default 10s untuk operasi perangkat tertentu.

{
   "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
}

Semua opsi konfigurasi dapat ditentukan pada baris perintah untuk mengganti setiap default yang diatur dalam file konfigurasi. Misalnya, opsi baris perintah --device_farmer_url dapat digunakan untuk mengganti URL DeviceFarmer yang diatur dalam file konfigurasi.

Penggunaan

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)

Bidang perangkat

Opsi --select dan --filter keduanya menggunakan "nama bidang" untuk melakukan tindakan masing -masing. Nama -nama lapangan ini adalah kunci JSON sebagaimana didefinisikan oleh DeviceFarmer sebagai bagian dari API REST -nya. Anda dapat melihat bidang yang didukung untuk instalasi DevICeFarmer Anda dengan menavigasi ke URL berikut: https://<device_farmer_url>/api/v1/devices/<serial> di mana device_farmer_url adalah url untuk instalasi devicefarmer Anda dan serial adalah angka serial dari satu nomor serial Anda adalah nomor serial dari satu serial adalah satu nomor serial perangkat Anda. Komponen /<serial> dapat dihilangkan untuk melihat semua bidang semua perangkat.

Nama lapangan mendukung notasi titik untuk mengakses tombol bersarang. Misalnya, battery.health dapat digunakan untuk mengakses kunci health bersarang dalam battery .

Perhatikan bahwa menentukan --filter bersama dengan --select akan secara otomatis menyertakan nama bidang apa pun yang ditentukan dalam filter di JSON yang dihasilkan.

Bidang yang biasa digunakan

abi - Antarmuka Biner Aplikasi Perangkat (mis. armeabi-v7a )
manufacturer - Produsen Perangkat
marketName - Nama Pemasaran Perangkat
model - Nama Model Perangkat
provider.name - STF Provider Hosting perangkat ini
version - Versi Android

Contoh

Hitung semua perangkat pada instance DeviceFarmer:

lariat --get-devices

Batasi bidang yang dikembalikan oleh --get-devices :

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

Perangkat filter berdasarkan bidang dan nilai spesifik (misalnya semua perangkat Samsung dengan level SDK 25-27):

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

Perangkat filter berdasarkan sub-kunci JSON menggunakan notasi titik:

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

Dorong file lokal ke perangkat dan jalankan:

lariat --exec-file path/to/hello

Jalankan perintah di semua perangkat ARM64:

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

Tekan file ke perangkat:

lariat --push-files path/to/files

Hasil

Lariat mengembalikan hasil untuk setiap perangkat yang memenuhi kriteria penyaringan.

Berikut ini adalah output sampel untuk perintah 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 " ,
}

Setiap hasil berisi berbagai bidang tergantung pada ketersediaan perangkat:

Jika perangkat tidak tersedia , hasilnya akan memiliki satu bidang:
- reason : Menentukan mengapa perangkat tidak tersedia untuk digunakan, seperti saat ini sedang digunakan, tidak ada di kisaran, dll.
Jika perangkat tersedia dan operasi dilakukan di atasnya, hasilnya akan mencakup dua bidang:
- output : Berisi output shell ADB dari perintah yang dieksekusi, atau detail tentang tindakan yang dilakukan.
- exitcode : Kode pengembalian perintah atau tindakan yang dieksekusi pada perangkat.

Ingatlah bahwa perangkat akan memiliki bidang 'alasan' (jika tidak tersedia) atau 'output' dan bidang 'keluar kode'

Gambar Docker

Untuk kenyamanan, gambar Lariat Docker resmi tersedia.

Untuk menggunakan gambar Docker, cukup jalankan

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

Perintah Docker Run ini membuat dan menjalankan wadah Docker berdasarkan ghcr.io/zetier/lariat:latest gambar. Itu melakukan tindakan berikut:

Membuat pemasangan volume hanya baca untuk direktori .android pada mesin host, yang berisi tombol ADB, ke direktori /root/.android di dalam wadah.
Membuat pemasangan volume hanya baca untuk direktori .lariat pada mesin host, yang berisi file konfigurasi Lariat, ke direktori /root/.lariat di dalam wadah.
Benderanya memastikan bahwa wadah secara otomatis dilepas setelah keluar.
Di dalam wadah, perintah lariat -c 'echo hello' dieksekusi, yang mencetak "halo" sebagai output pada setiap perangkat yang dapat dikunci pada rentang DeviceFarmer Anda.

Harap perhatikan bahwa jika tombol ADB dan file konfigurasi Anda terletak di direktori yang berbeda pada mesin host, Anda mungkin perlu memodifikasi perintah Run Docker sesuai untuk menyediakan jalur yang benar untuk pemasangan volume.

Integrasi CI

Lariat dirancang untuk integrasi sederhana ke dalam pipa CI. Di bawah ini adalah contoh pekerjaan gitlab yang menguji biner yang dibangun di dalam pipa pada rentang DeviceFarmer:

 .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

Catatan

Lariat akan mengunci perangkat sebelum melakukan operasi apa pun untuk memastikan akses eksklusif. Setelah operasi selesai, perangkat akan dibuka.
Pastikan untuk memberikan jalur yang benar ke file kunci pribadi ADB melalui ~/.lariat/config.json jika berbeda dari lokasi default ( ~/.android/adbkey )
Secara default, Lariat akan menyebutkan ~~setiap~~ Perangkat pada rentang DeviceFarmer, termasuk yang tidak present atau ready . Anda dapat memodifikasi ini sesuai kebutuhan dengan menentukan --filter ready=true present=true jika diperlukan.

Instalasi Pengembangan

Catatan: Lariat dikembangkan dan diuji secara teratur dengan Ubuntu 18.04 dengan Python 3.8. Distribusi dan versi lain mungkin berhasil, tetapi saat ini belum teruji.

Klon Repositori

Instal dependensi bersama dengan paket 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 .