במדריך הזה מוסבר איך להריץ בדיקת אינסטרומנטציה של Android או קובץ הפעלה עצמאי של Android באמצעות ה-CLI של gcloud beta device-run, ואיך למצוא את התוצאות במסוף Google Cloud . אנחנו יוצאים מנקודת הנחה שיש לכם חשבון ופרויקט ב- Google Cloud .
אם אתם עוברים מ-Firebase Test Lab ל-Developer Device Platform, כדאי לעיין במדריך להעברת נתונים, במדריך לתרגום פקודות ודגלים ובמיומנות ההעברה לסוכני AI.
כדי להשתמש ב-Google Cloud CLI, תצטרכו לספק את מזהה הפרויקט ב- Google Cloud . במאמר gcloud beta device-run מופיע סיכום של הפקודות.
לפני שמתחילים
השלבים האלה מניחים שכבר:
- יצרתם פרויקט ב- Google Cloud .
- מגדירים את Developer Device Platform לפי המדריך למתחילים.
- האימות בוצע באמצעות
gcloudבטרמינל. - עיינתי בסקירה הכללית של הרצה במכשיר כדי לקבל מידע כללי.
- בניתם בדיקה עם כלים ל-Android, או הכנתם קובץ הפעלה עצמאי ל-Android (כמו קובץ בינארי מקומפל של C++, כלי להרצת השוואת ביצועים או סקריפט מעטפת).
שלב 1. הגדרת הבדיקה או הרצת קובץ ההפעלה
אחרי שמריצים סשן, אפשר לבדוק כמה אפשרויות הגדרה:
אפשרויות לבדיקות אינסטרומנטציה ולקובצי הפעלה
- כמה מכשירים: כדי להריץ את אותה בדיקה או קובץ הפעלה בכמה מכשירים, צריך לספק את האפשרות
--deviceעם כמה מזהי מכשירים שמופרדים באמצעות פסיקים, כמו--device shiba-34,tokay-36, או עם כמה אפשרויות--device, כשכל אחת מציינת מזהה מכשיר נפרד (לדוגמה,--device shiba-34 --device tokay-36). - העברת קבצים למכשיר: העברת קבצים נוספים (כמו משקלים של מודל ML, קלט לבדיקה או ספריות משותפות של
.so) למכשיר לפני ההרצה באמצעות--other-files-to-push=SOURCE=DEST,.... SOURCEתומך גם בנתיבים מקומיים וגם בנתיבים של Cloud Storage (gs://...), ו-DESTהוא נתיב היעד במכשיר. - שליפת קבצים מהמכשיר: שליפת קבצים או ספריות שנוצרו מהמכשיר אחרי שההרצה מסתיימת באמצעות
--paths-to-pull=DEVICE_PATH,.... - קטגוריה מותאמת אישית של Cloud Storage: מציינים שם של קטגוריה קיימת של Cloud Storage (בלי סכימה או נתיב של
gs://) באמצעות--bucket-name=. אם לא מציינים קטגוריה, Google Cloud CLI משתמש בקטגוריית ברירת מחדל בשםPROJECT_ID-devicerunאו יוצר אותה. - ניסיונות חוזרים של בדיקות לא יציבות (flaky tests): הגדירו את מספר הניסיונות המקסימלי לכל משימה או פיצול כדי לטפל בחוסר היציבות:
--flaky-test-attempts=3(ברירת המחדל היא ניסיון אחד (1)). - סביבת המכשיר ואבחון: הגדרת כיוון המכשיר (
--orientation=portraitאוlandscape), הלוקאל (--locale=en-US), מיקום GPS מדומה (--coordinates=LATITUDE,LONGITUDE), הקלטת וידאו של המסך (--video=alwaysאוon-failure), איסוףdumpsys(--dumpsys=alwaysאוon-failure) או איסוףbugreport(--bugreport=alwaysאוon-failure). - Labels: צירוף תוויות מפתח/ערך שהוגדרו על ידי המשתמש לסשן באמצעות
--labels=KEY=VALUE,....
אפשרויות לבדיקת אינסטרומנטציה
- אפליקציות נוספות: אפשר לציין קובץ APK, AAB או APKS אחד או יותר להתקנה לפני הפעלת הבדיקות באמצעות הדגל
--apps=path1,path2,...,path_n. הסדר שאתם מציינים הוא הסדר שבו האפליקציות האלה מותקנות. - זמן קצוב לתפוגה של בדיקה: הגבלת משך הביצוע:
--instrumentation-timeout=10m(הטווח החוקי הוא1mעד3hוברירת המחדל היא5m).
אפשרויות הפעלה ב-Android
- ארגומנטים של קובץ הפעלה: מעבירים ארגומנטים של שורת פקודה לקובץ ההפעלה באמצעות
--executable-args=ARG,...כרשימה מופרדת בפסיקים או על ידי חזרה על הדגל. כל רכיב הופך לארגומנט אחד, לכן צריך לשכתב שורות פקודה שמופרדות ברווחים לצורה שמופרדת בפסיקים (לדוגמה,--executable-args="--input=a.file,--threads=4"). כדי להעביר ארגומנט שמכיל פסיק, צריך להוסיף את הקידומת^SEP^לערך כדי לציין מפריד אחר (לדוגמה,--executable-args="^;^--shape=1,224,224,3;--threads=4"). - משתני סביבה: הגדרה של משתני סביבה לתהליך ההפעלה במכשיר באמצעות
--executable-env-vars=KEY=VALUE,...(לדוגמה,--executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib). - זמן קצוב להפעלה: הגבלת משך ההפעלה של הקובץ שניתן להפעלה:
--executable-timeout=10m(הטווח התקין הוא1mעד3h, וערך ברירת המחדל הוא5m, לא כולל זמן ההכנה והניקוי של המכשיר).
הרצות סינכרוניות ואסינכרוניות
כברירת מחדל, פקודת השליחה היא חסימה (סינכרונית). הוא ימתין עד שהבדיקה או קובץ ההפעלה יסתיימו, ואז ידפיס טבלת סיכום של התוצאות.
כדי לשלוח את הסשן ולחזור מיד אחרי העלאת הקבצים ל-Cloud Storage, מוסיפים את הדגל --async:
בדיקת אינסטרומנטציה ב-Android
במקרה של :
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--async
קובץ הפעלה של Android
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--async
הפעולה הזו מחזירה מזהה סשן באופן מיידי. אחר כך אפשר להמתין להשלמת הפעולה באמצעות הפקודה sessions wait:
gcloud beta device-run sessions wait SESSION_ID
הפקודה תחסום עד שהמשימה תושלם.
מספר מכשירים
כדי להריץ את אותו מבחן או קובץ הפעלה בכמה מכשירים, צריך לספק את האפשרות --device עם כמה מזהי מכשירים שמופרדים באמצעות פסיקים, או עם כמה אפשרויות --device, כשכל אחת מציינת מזהה מכשיר נפרד.
בדיקת אינסטרומנטציה ב-Android
gcloud beta device-run sessions submit instrumentation \
--device shiba-34,tokay-36 \
--test ./ANDROID_TESTS.apk
או:
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--device tokay-36 \
--test ./ANDROID_TESTS.apk
קובץ הפעלה של Android
gcloud beta device-run sessions submit android-executable \
--device shiba-34,tokay-36 \
--executable ./MY_EXECUTABLE
או:
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--device tokay-36 \
--executable ./MY_EXECUTABLE
זמן קצוב לתפוגה של בדיקה וקובץ הפעלה
הגבילו את משך ההרצה של הבדיקה או של קובץ ההפעלה:
בדיקת אינסטרומנטציה ב-Android
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--instrumentation-timeout=10m
קובץ הפעלה של Android
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--executable-timeout=10m
הטווח החוקי הוא 1m עד 3h להפעלות ב-Android, וברירת המחדל היא 5m.
גרסאות התוכנה
לפני שמגדירים הרצות של בדיקות, אפשר למצוא ולהשתמש בחבילות תוכנה ובגרסאות זמינות של AndroidX Test Orchestrator ולבדוק את מחזורי החיים, הגרסאות הנתמכות והמטא-נתונים שלהן.
קודם כל, צריך לרשום את כל חבילות התוכנה הזמינות והגרסאות שלהן:
gcloud beta device-run software-versions list
הפלט שמתקבל דומה לזה:
ID NAME SOFTWARE_TYPE VERSION STATE IS_DEFAULT
androidx-test-orchestrator-1-4-1 AndroidX Test Orchestrator 1.4.1 ANDROIDX_TEST_ORCHESTRATOR 1.4.1 ACTIVE True
androidx-test-orchestrator-1-6-1 AndroidX Test Orchestrator 1.6.1 ANDROIDX_TEST_ORCHESTRATOR 1.6.1 ACTIVE
xcode-16-4 Xcode 16.4 XCODE 16.4 ACTIVE
xcode-26-2 Xcode 26.2 XCODE 26.2 ACTIVE True
אחר כך מתארים חבילה ספציפית באמצעות מזהה המשאב המדויק שלה מהרשימה:
gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1
הפלט שמתקבל דומה לזה:
id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1
עכשיו, כשאתם יודעים אילו גרסאות תוכנה זמינות, אתם יכולים להשתמש בהן בהרצות הבדיקה באמצעות הדגל --orchestrator-version, באופן הבא:
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
מידע נוסף זמין במאמר בנושא הפעלת Orchestrator.
הפעלת Orchestrator
בבדיקות אינסטרומנטציה, פלטפורמת Developer Device Platform תומכת בתזמור בדיקות ל-Android, שמאפשר להריץ כל אחת מהבדיקות של האפליקציה בהפעלה משלה של Instrumentation.
כשמשתמשים ב-Orchestrator:
מומלץ להימנע ממצב משותף. כל בדיקה פועלת במופע
Instrumentationמשלה. לכן, אם הבדיקות שלכם משתפות את מצב האפליקציה, רוב המצב המשותף הזה מוסר מהמעבד או מהזיכרון של המכשיר אחרי כל בדיקה. כדי להסיר את כל המצב המשותף מהמעבד ומהזיכרון של המכשיר אחרי כל בדיקה, צריך לכלול את ההגדרהclearPackageDataבאופן הבא:--additional-test-options clearPackageData=trueבידוד קריסות. אם בדיקה אחת קורסת, היא משביתה רק את המופע שלה ב-
Instrumentation. זה אומר שהבדיקות האחרות עדיין פועלות ומספקות תוצאות בדיקה מלאות.
ב-Developer Device Platform, תזמור בדיקות ל-Android מושבת כברירת מחדל. כדי להפעיל את Orchestrator ולציין את הגרסה שבה רוצים להשתמש במהלך הפעלת הבדיקה, מעבירים את הגרסה שבחרתם לדגל --orchestrator-version=ORCHESTRATOR_VERSION בפקודה sessions submit
instrumentation, כך:
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
מגדירים את הדגל לערך auto כדי להשתמש בגרסת ברירת המחדל של המערכת של Orchestrator.
שלב 2. בחירת מכשירים
באמצעות device-run CLI, אפשר להריץ בדיקות וקבצים הפעלה של Android במכשירים פיזיים ומכשירים וירטואליים זמינים. כדי לראות את הרשימה המלאה של המכשירים הזמינים, אפשר להיכנס לקטלוג המכשירים האינטראקטיבי או להריץ את הפקודה:
gcloud beta device-run devices list
פלט לדוגמה:
ID MAKE NAME MODEL FORM OS_VERSION CAPACITY AVAILABILITY PRODUCTS
tegu-35 Google Pixel 9a tegu PHYSICAL 35 MEDIUM LOW Automation, Streaming
tokay-34 Google Pixel 9 tokay PHYSICAL 34 HIGH HIGH Automation, Streaming
בקטלוג המכשירים מוסבר איך לסנן את הרשימה הזו. כדי להריץ את המשימה במכשיר ספציפי, משתמשים במזהה המתאים (לדוגמה, tegu-35) בפקודת השליחה.
שלב 3. מריצים את הבדיקה או את קובץ ההפעלה
אפשר לשלוח APK של בדיקת מכשור ל-Android או קובץ הפעלה עצמאי ל-Android.
הרצת בדיקת אינסטרומנטציה
שימו לב שהדגלים האלה נדרשים לבדיקות אינסטרומנטציה ב-Android:
- מכשיר: מציינים מכשיר באמצעות
--device:--device shiba-35 - Test: מציינים את קובץ ה-APK של הבדיקה באמצעות
--test:--test /path/to/test.apk
כדי להריץ את בדיקת האינסטרומנטציה, מפעילים פקודת sessions submit
instrumentation שדומה לפקודה הבאה, עם מזהי המכשירים ונתיב הבדיקה שלכם:
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--apps /path/to/app.apk \
--test /path/to/test.apk
הפעלת קובץ הפעלה של Android
כדי להריץ קובץ הפעלה עצמאי (כמו קובץ בינארי של C++ שעבר קומפילציה, כלי להשוואה בין ביצועים של למידת מכונה במכשיר כמו LiteRT, או סקריפט מעטפת) ישירות במכשיר Android בלי לארוז אותו ב-APK, משתמשים בפקודה sessions submit
android-executable.
שימו לב שהדגלים האלה נדרשים לקובצי הפעלה של Android:
- מכשיר: מציינים מכשיר באמצעות
--device:--device shiba-35 - קובץ הפעלה: מציינים את הנתיב המקומי או הנתיב ב-Cloud Storage לקובץ ההפעלה באמצעות
--executable:--executable /path/to/my_executable
כדי להריץ את קובץ ההפעלה, מזינים פקודה שדומה לפקודה הבאה, עם מזהי המכשירים ונתיב קובץ ההפעלה שלכם:
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--executable /path/to/my_executable \
--executable-args="--input=/data/local/tmp/file.name,--threads=4" \
--other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
--paths-to-pull=/data/local/tmp/output
תיקיית דוח התוצאות של המשימה נמצאת בנתיב של Cloud Storage, כמו gs://BUCKET_NAME/automation/sessions/SESSION_ID/. בפלט הפקודה, מחפשים את הקישור שנראה כך: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.
שלב 4. שימוש ב-sharding
כדי לכלול בדיקות אינסטרומנטציה של פלטפורמת מכשירי הפיתוח בתהליך עבודה של אינטגרציה רציפה (CI) ופיתוח רציף (CD), כדאי לפצל את הבדיקות. חלוקת בדיקות (Test sharding) מחלקת קבוצה של בדיקות אינסטרומנטציה לקבוצות משנה (shards) שפועלות בנפרד ובבידוד. פלטפורמת Developer Device Platform מריצה באופן אוטומטי כל שבר (shard) במקביל באמצעות כמה מכשירים, ומשלימה את כל קבוצת הבדיקות בפחות זמן.
שלב 4.1. בחירת אפשרות חלוקה לפלחים (sharding)
אם למשימות שלכם יש רק מספר קטן של מקרי בדיקה, או שזמן הביצוע הכולל של כל מקרי הבדיקה לא ארוך, אין צורך להשתמש בפיצול. אם יש לכם מספר גדול של מקרי בדיקה, או שזמן הביצוע הכולל של כל מקרי הבדיקה ארוך, כדאי להשתמש בפיצול.
ב-Developer Device Platform יש תמיכה גם בפיצול חכם וגם בפיצול אחיד. כשמחליטים איך לפצל את הבדיקות, כדאי לשקול את האפשרויות הבאות:
אם כל מקרי הבדיקה יימשכו זמן דומה, אפשר להשתמש בחלוקה אחידה לשברים (shards) על ידי חלוקת כל מקרי הבדיקה ל-
nשברים.כשזמן הביצוע של מקרי בדיקה שונים משתנה באופן משמעותי, כדאי להשתמש בפיצול חכם. כדי ליצור מקטעים שונים, המערכת של Developer Device Platform משתמשת בהיסטוריית זמני ביצוע הבדיקות, ומנסה להשלים את כל המקטעים בפרק זמן דומה.
פיצול אחיד
כדי לפצל את הבדיקות באמצעות פיצול אחיד, צריך לכלול את הדגלים --sharding-option=uniform ו---uniform-sharding-count= בפקודה sessions submit instrumentation, באופן הבא:
gcloud beta device-run sessions submit instrumentation \
--test path/to/test.apk \
--device shiba-34,tokay-36 \
--sharding-option=uniform \
--uniform-sharding-count=2
אמור להופיע פלט שמציין Job status: 2 running. השירות יוצר שתי משימות, אחת לכל מכשיר. מכיוון שהקלט בשתי המשימות זהה, השירות מבצע אימות מרכזי, כלומר רק פעם אחת.
בפלט הסופי של הפקודה, שתי המשימות יופיעו בנפרד:
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 execution-000 PASSED
job-001 execution-000 PASSED
חלוקה חכמה
כדי לפצל את הבדיקות באמצעות פיצול חכם, צריך לכלול את הדגלים --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (בדקות או 1h) ו---smart-sharding-record-name= בפקודה sessions
submit instrumentation, באופן הבא:
gcloud beta device-run sessions submit instrumentation \
--test path/to/test.apk \
--device shiba-34,shiba-35,tokay-36 \
--sharding-option=smart \
--smart-sharding-max-shard-count=3 \
--smart-sharding-target-duration=5m \
--smart-sharding-record-name=test.yaml
הפלט הסופי אמור להראות ששלוש משימות הופעלו:
Session [session-3cd0564a] finished with result [ERROR].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 execution-000 PASSED
job-001 execution-000 PASSED
job-002 execution-000 PASSED
זה סיכום של הדגלים של חלוקה חכמה למקטעים שמשמשים כאן:
--smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT– מציינים את המספר המקסימלי של רסיסים שייווצרו עבור חלוקה חכמה לרסיסים. אם המדיניות לא מוגדרת או מוגדרת כ-0, המערכת משתמשת במגבלות המקסימליות שהוגדרו בה. הטווח התקין הוא 0 עד 20 למכשירים פיזיים ו-0 עד 200 למכשירים וירטואליים.
--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION– מציינים את זמן הביצוע המטורגט (למשל, 2m, 10m, 1h) לכל פיצול חכם. הטווח התקין הוא מ-2 דקות עד שעה אחת. חובה כש---sharding-option=smart.
--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME– מציינים את השם של קובץ הרשומה של חלוקה חכמה ל-shards, בלי סיומת הקובץ. חובה כשמשתמשים ב---sharding-option=smart. קובץ ה-YAML הזה נמצא בקטגוריית האחסון של Google Cloudשצוינה על ידי--bucket-nameבספרייהsmart-sharding/. אם הקובץ לא קיים, הוא ייווצר באופן אוטומטי. אחרת, התוכן שלו יעודכן בסיום הסשן.
שלב 5. עיון בנתונים של הרצת הבדיקה וניהול שלהם
גם בפקודות sessions submit instrumentation ו-sessions submit android-executable במצב אסינכרוני וגם במצב סינכרוני, אפשר להשתמש בפקודה sessions
describe כדי לשלוח שאילתה לגבי סטטוס העבודה במהלך ההפעלה, או לקבל את התוצאה אחרי שהיא מסתיימת:
gcloud beta device-run sessions describe SESSION_ID
הפלט מסכם את תוצאות הבדיקה ומקשר לתוצאות ב Google Cloud מסוף. לדוגמה:
Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 all FAILED: 2 test cases failed, 5 passed
כדי לראות רשימה של כל הסשנים הפעילים והסשנים שהסתיימו, מריצים את הפקודה הבאה:
gcloud beta device-run sessions list
מקבלים פלט שמכיל את רשימת הסשנים בפרויקט, שדומה לזה:
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
session-911d0763 2026-07-09T00:39:02.051Z DONE
session-4e943fea 2026-07-15T23:08:32.252Z DONE
session-0132e458 2026-08-20T18:33:19.751Z DONE
session-1077f07b 2026-07-28T22:35:43.848Z DONE
session-71b054c6 2026-07-15T01:15:41.643Z DONE
session-4f8b2e45 2026-08-06T23:11:56.161Z DONE
הפקודה sessions list תומכת בכל אפשרויות הדגלים הרגילות של Google Cloud CLI. לדוגמה:
gcloud beta device-run sessions list --limit 5
התוצאה היא:
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce 2026-07-03T05:10:58.015Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
לחלופין, כדי לראות את כל הסשנים הפעילים, מריצים את הפקודה:
gcloud beta device-run sessions list --filter RUNNING
אם יש לכם סשנים פעילים, תראו תוצאות דומות לאלה:
SESSION_ID START_TIME STATE
session-d7ff8b81 RUNNING
אחרת, תקבלו Listed 0 items.
כדי לבטל סשן פעיל, מריצים את הפקודה הבאה עם מזהה הסשן:
gcloud beta device-run sessions cancel SESSION_ID
הפקודה מוחזרת באופן מיידי, כי הסשן מסומן רק לביטול. הביטול מתבצע באופן אסינכרוני בקצה העורפי.
אם הסשן כבר הסתיים, רק הסטטוס הנוכחי מודפס. בקשה לביטול סשן שהסתיים היא לא שגיאה.
המאמרים הבאים
השלב הבא הוא חיפוש וניתוח של יומנים.