lariat
v0.2.0
Lariat هي أداة سطر أوامر قوية مصممة لتبسيط تنفيذ الأوامر وتشغيل التنفيذيين على أجهزة Android عن بعد. إنه يحقق هذا من خلال الاستفادة من واجهة برمجة تطبيقات DeviceFarmer و Android Debug Bridge (ADB). مع الولادة ، يتم تبسيط العملية المرهقة للاتصال يدويًا بالأجهزة ودفع الملفات وتشغيل الأوامر واسترداد النتائج وجعلها أكثر كفاءة. إنه حل مثالي لأتمتة المهام في خطوط أنابيب التكامل المستمر (CI).
الولادة متوفرة على PYPI:
python -m pip install lariatلاريات يدعم رسميا بيثون 3.8+.
يستخدم Lariat ملف تكوين JSON. الموقع الافتراضي لملف التكوين هذا في دليل .lariat داخل الدليل الرئيسي للمستخدم ( ~/.lariat/config.json ). يتم استخدام ملف التكوين لتحديد ما يلي:
device_farmer_url : عنوان URL لمثيل DeviceFarmer للاتصال بـ.
.json أو .yaml . access_token : رمز الوصول إلى DeviceFarmer.
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> where device_farmer_url هو عنوان URL لتثبيت الجهاز والسلسلة هو العدد السلسل serial هو رقم تسلسلي للسلسلة. من أجهزتك. يمكن حذف المكون /<serial> لعرض جميع الحقول لجميع الأجهزة.
تدعم أسماء الحقل تدوين DOT للوصول إلى المفاتيح المتداخلة. على سبيل المثال ، يمكن استخدام battery.health للوصول إلى مفتاح health المتداخل داخل battery .
لاحظ أن تحديد --filter إلى جانب --select تلقائيًا بتضمين أي أسماء حقل محددة في المرشح في JSON الناتج.
abi - واجهة تطبيق الجهاز الثنائية (على سبيل المثال. armeabi-v7a )manufacturer - الشركة المصنعة للأجهزةmarketName - اسم تسويق الجهازmodel - اسم طراز الجهازprovider.name - مزود STF يستضيف هذا الجهاز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/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 : يحتوي على إخراج SHELL ADB للأمر الذي تم تنفيذه ، أو تفاصيل حول الإجراء الذي تم تنفيذه.exitcode : رمز الإرجاع للأمر أو الإجراء الذي تم تنفيذه على الجهاز.تذكر أن الجهاز إما سيكون له حقل "سبب" (إذا كان غير متوفر) أو "إخراج" و "exitcode"
للراحة ، تتوفر صورة رسمية لاريات دوكر.
لاستخدام صورة 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 على الجهاز المضيف ، والذي يحتوي على ملف تكوين الولادة ، إلى دليل /raot/.lariat داخل الحاوية.
يضمن علامة -RM إزالتها تلقائيًا بعد خروجها.
داخل الحاوية ، يتم تنفيذ Armiat lariat -c 'echo hello' ، والذي يطبع "Hello" كإخراج على كل جهاز قابل للقفل على نطاق DeviceFarmer الخاص بك.
يرجى ملاحظة أنه إذا كانت مفاتيح ADB وملف التكوين الخاص بك موجودة في أدلة مختلفة على جهاز المضيف ، فقد تحتاج إلى تعديل أمر Docker Run وفقًا لتوفير المسارات الصحيحة لتركيب الصوت.
تم تصميم Lariat للتكامل البسيط في خطوط أنابيب CI. فيما يلي مثال على وظيفة gitlab التي تختبر ثنائيًا مدمجًا في خط الأنابيب على نطاق 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
ستقوم Lariat بإغلاق الأجهزة قبل إجراء أي عمليات لضمان الوصول الحصري. بعد الانتهاء من العمليات ، سيتم إلغاء قفل الأجهزة.
تأكد من توفير المسار الصحيح لملف المفتاح الخاص ADB عبر ~/.lariat/config.json إذا كان مختلفًا عن الموقع الافتراضي ( ~/.android/adbkey )
بشكل افتراضي ، سوف يعدد الولادة كل الجهاز على نطاق DeviceFarmer ، بما في ذلك تلك غير present أو ready . يمكنك تعديل هذا حسب الحاجة من خلال تحديد --filter ready=true present=true إذا لزم الأمر.
ملاحظة: تم تطوير الولادة واختبارها بانتظام مع Ubuntu 18.04 مع Python 3.8. قد تعمل التوزيعات والإصدارات الأخرى ، ولكنها حاليًا لم يتم اختبارها.
استنساخ المستودع
تثبيت التبعيات جنبا إلى جنب مع حزمة 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 .إنشاء ملف تكوين
المساهمات مرحب بها! إذا وجدت أي مشكلات أو لديك اقتراحات للتحسينات ، فيرجى فتح مشكلة أو إرسال طلب سحب.
هذا المشروع مرخص بموجب ترخيص GPLV2.
