Developer Device Platform Device Run for Android

במדריך הזה מוסבר איך להריץ בדיקת אינסטרומנטציה של 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 מופיע סיכום של הפקודות.

לפני שמתחילים

השלבים האלה מניחים שכבר:

  1. יצרתם פרויקט ב- Google Cloud .
  2. מגדירים את Developer Device Platform לפי המדריך למתחילים.
  3. האימות בוצע באמצעות gcloud בטרמינל.
  4. עיינתי בסקירה הכללית של הרצה במכשיר כדי לקבל מידע כללי.
  5. בניתם בדיקה עם כלים ל-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

הפקודה מוחזרת באופן מיידי, כי הסשן מסומן רק לביטול. הביטול מתבצע באופן אסינכרוני בקצה העורפי.

אם הסשן כבר הסתיים, רק הסטטוס הנוכחי מודפס. בקשה לביטול סשן שהסתיים היא לא שגיאה.

המאמרים הבאים

השלב הבא הוא חיפוש וניתוח של יומנים.