הרצה במכשיר של Developer Device Platform למכשירי 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.

שלב 1. הגדרת הבדיקה

אפשרויות לבדיקות אינסטרומנטציה ב-Android

  • כמה מכשירים: כדי להריץ את אותה בדיקה בכמה מכשירים, צריך לציין את הדגל --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).

הרצות סינכרוניות ואסינכרוניות

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

כדי לשלוח את הסשן ולחזור מיד אחרי העלאת הקבצים ל-Cloud Storage, מוסיפים את הדגל --async:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

הפעולה הזו מחזירה מזהה סשן באופן מיידי. אפשר להמתין לסיום הפעולה באמצעות הפקודה sessions wait:

gcloud beta device-run sessions wait SESSION_ID

הפקודה תחסום עד שהמשימה תושלם.

מספר מכשירים

כדי להריץ את אותה בדיקה בכמה מכשירים, צריך לציין את הדגל --device עם כמה מזהי מכשירים שמופרדים בפסיקים, או עם כמה דגלי --device, כשכל אחד מהם מציין מזהה מכשיר נפרד:

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

זמן קצוב לתפוגה של בדיקה

הגבלת משך ההרצה של הבדיקה:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

הטווח התקין הוא 1m עד 3h, וערך ברירת המחדל הוא 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

פלטפורמת Developer Device Platform תומכת בתזמור בדיקות ל-Android, שמאפשר להריץ כל אחת מהבדיקות של האפליקציה בהפעלה משלה של Instrumentation.

כשמשתמשים ב-Orchestrator:

  • מומלץ להימנע ממצב משותף. כל בדיקה פועלת במכונה משלה של Instrumentation. לכן, אם הבדיקות שלכם משתפות את מצב האפליקציה, רוב המצב המשותף הזה מוסר מהמעבד או מהזיכרון של המכשיר אחרי כל בדיקה. כדי להסיר את כל המצבים המשותפים מהמעבד ומהזיכרון של המכשיר אחרי כל בדיקה, צריך לכלול את ההגדרה clearPackageData באופן הבא: --additional-test-options clearPackageData=true

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

כברירת מחדל, הכלי "תזמור בדיקות ל-Android" מושבת ב-Developer Device Platform. כדי להפעיל את 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. בחירת מכשירים

באמצעות ה-CLI של device-run, אפשר להריץ בדיקות של 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:

  • מכשיר: מציינים מכשיר באמצעות --device: --device shiba-35
  • בדיקה: מציינים את ה-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

תיקיית דוח התוצאות של המשימה נמצאת בנתיב של Cloud Storage, כמו gs://BUCKET_NAME/automation/sessions/SESSION_ID/. בפלט הפקודה, מחפשים את הקישור שנראה כך: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

שלב 4. שימוש בפיצול (sharding)

כדי לכלול בדיקות אינסטרומנטציה של Developer Device Platform בתהליך עבודה של אינטגרציה רציפה (CI) ופיתוח רציף (CD), כדאי לפצל את הבדיקות. פיצול בדיקות מחלק קבוצה של בדיקות אינסטרומנטציה לקבוצות משנה (פיצולים) שפועלות בנפרד ובבידוד. פלטפורמת Developer Device Platform מריצה באופן אוטומטי כל פיצול במקביל באמצעות כמה מכשירים, ומשלימה את כל קבוצת הבדיקות בפחות זמן.

שלב 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 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

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

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

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

בשלב הבא, מריצים קובץ הפעלה של Android או מוצאים ומנתחים יומנים.