מעבר מ-Firebase Test Lab ומ-Flank ל-Developer Device Platform עם AI

הסקיל הזה עוזר לתרגם תהליכי עבודה והגדרות קודמות של הרצת בדיקות (מ-Flank או מ-gcloud firebase test) לממשק המודרני של gcloud beta device-run CLI שמבוסס על משאבים (ול-gcloud alpha device-run לשליחת סשנים של iOS XCTest).

מיפוי המבנה של הפקודות והמשאבים

ב-CLI של "הרצה במכשיר", הפקודות מאורגנות לפי משאבים: devices, software-versions ו-sessions:

1. קטלוג המכשירים (devices)

  • רשימת מכשירים:
    • גרסה קודמת: gcloud firebase test android/ios models list
    • חדש: gcloud beta device-run devices list [--filter="..."]
    • דוגמה: gcloud beta device-run devices list --filter="platform:android"
  • תיאור המכשיר:
    • גרסה קודמת: gcloud firebase test android/ios models describe {MODEL}
    • חדש: gcloud beta device-run devices describe {DEVICE}
    • דוגמה: gcloud beta device-run devices describe redfin-30
  • בדיקת קיבולת המכשירים והזמינות של צי המכשירים:
    • גרסה קודמת: gcloud firebase test android/ios list-device-capacities
    • חדש: מוטמע ישירות במשאב המכשיר (availability.capacity ו-availability.available). אפשר לבדוק באמצעות gcloud beta device-run devices describe {DEVICE} או לסנן ישירות באמצעות gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH".

2. גרסאות התוכנה (software-versions)

  • רשימת גרסאות התוכנה הנתמכות (Xcode ותזמור בדיקות ל-Android):
    • גרסה קודמת: gcloud firebase test ios xcode-versions list
    • חדש: gcloud beta device-run software-versions list
  • תיאור גרסת התוכנה:
    • חדש: gcloud beta device-run software-versions describe {SOFTWARE_VERSION}
    • דוגמה: gcloud beta device-run software-versions describe xcode-16-4

3. סשנים של אוטומציה (sessions)

  • שליחת נתוני אינסטרומנטציה של Android:
    • גרסה קודמת: gcloud firebase test android run --type=instrumentation ...
    • חדש: gcloud beta device-run sessions submit instrumentation ...
  • שליחת iOS XCTest:
    • גרסה קודמת: gcloud firebase test ios run --type=xctest ...
    • חדש: gcloud alpha device-run sessions submit xctest ...
  • המתנה לסיום הסשן:
    • מדור קודם: חסימה סינכרונית של CLI בלבד
    • חדש: gcloud beta device-run sessions wait {SESSION}
  • תיאור / בדיקת סשן:
    • גרסה קודמת: הצגת קישור לדף אינטרנט אחר במסוף Firebase או בתוצאות של Cloud Tool
    • חדש: gcloud beta device-run sessions describe {SESSION} [--full]
  • רשימת סשנים קודמים:
    • גרסה קודמת: הצגת היסטוריית המטריצה במסוף האינטרנט
    • חדש: gcloud beta device-run sessions list
  • ביטול הסשן:
    • הגרסה הקודמת: מסוף אינטרנט בלבד (ללא פקודת CLI)
    • חדש: gcloud beta device-run sessions cancel {SESSION}

טבלת עזר למיפוי דגלים

בטבלה הבאה מופיעים פרמטרים מגרסאות קודמות של Firebase Test Lab ו-Flank, והפרמטרים המקבילים שנתמכים ב-gcloud beta device-run:

סוג הבדיקה קבוצת תכונות פרמטר מדור קודם (Firebase או Flank) פרמטר היעד (device-run) פורמט / לוגיקת המרה
נפוצות (Android ו-iOS) פרמטרים ונכסים עיקריים צד --project --project דגל גלובלי סטנדרטי של Google Cloud (--project=PROJECT_ID) או הגדרה פעילה של Google Cloud CLI.
נפוצות (Android ו-iOS) פרמטרים ונכסים עיקריים --client-details --labels מילון של צמדי מפתח=ערך.
נפוצות (Android ו-iOS) פרמטרים ונכסים עיקריים --other-files --other-files-to-push מילון של קבצים שצריך להעביר לפני הרצת הבדיקה (SOURCE=DEVICE_PATH ב-Android,‏ SOURCE=BUNDLE_ID:DEVICE_PATH ב-iOS).
נפוצות (Android ו-iOS) הגדרה וטירגוט של מכשירים --device model={M},version={V} --device={M}-{V} מיפוי של דגם המכשיר וגרסת מערכת ההפעלה למחרוזת מזהה של --device. אפשר להזין רשימה מופרדת בפסיקים של כמה מכשירים בדגל אחד (למשל, --device=mediumphone-arm-32,shiba-36).
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות --async --async מפות 1:1. כברירת מחדל, הפקודה נשארת סינכרונית. צריך להעביר את הפרמטר הזה כדי שהיא תחזור מיד. מעקב או המתנה באמצעות gcloud beta device-run sessions wait <SESSION_ID>.
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות --num-flaky-test-attempts {R} --flaky-test-attempts {A} מספר שלם. ממירים את מספר ניסיונות השליחה החוזרת $R$ למגבלת הניסיונות הכוללת: $A = R + 1$ (ברירת המחדל היא 1).
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות --num-uniform-shards {N} --sharding-option=uniform
--uniform-sharding-count={N}
הגדרת הדגל מפעילה אסטרטגיית פיצול אחידה (טווח ספירה חוקי: 1-20 פיזיים, 1-200 וירטואליים; iOS מציעה מכשירים פיזיים בלבד).
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות צד --shard-time {S} --sharding-option=smart
--smart-sharding-target-duration={S}
הפעלת חלוקה חכמה של נתונים עם זמן ביצוע מטורגט (למשל, ‫2m, ‏10m, ‏1h). הטווח התקין: 2m עד 1h.
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות פלנק --smart-flank-gcs-path --smart-sharding-record-name={name}
--bucket-name={bucket}
השם של קובץ ה-YAML של רשומת הפיצול (ללא הסיומת) בתוך --bucket-name ב-automation/smart-sharding/.
נפוצות (Android ו-iOS) בקרה על ביצוע בקשות ובעיות של חוסר יציבות צד --max-test-shards {N} --smart-sharding-max-shard-count={N} ממפה לגבול מקסימלי של פיצול כשהפיצול החכם מופעל (0-20 פיזי, 0-200 וירטואלי; iOS מציעה מכשירים פיזיים בלבד).
נפוצות (Android ו-iOS) פלט ואחסון --results-bucket --bucket-name הקטגוריה שאליה מועלים פריטי המידע שנוצרו בפלט של הבדיקה (ברירת המחדל היא gs://[PROJECT_ID]-devicerun).
נפוצות (Android ו-iOS) פלט ואחסון --results-dir ניהול אוטומטי אי אפשר להגדיר תיקיות משנה מותאמות אישית. כל פריטי המידע שנוצרים במהלך הבדיקה מאורגנים באופן אוטומטי בתיקייה automation/sessions/{session_id}/ בתוך הקטגוריה שצוינה ב---bucket-name.
נפוצות (Android ו-iOS) פלט ואחסון --record-video --video הערכים התקינים: always או on-failure.
נפוצות (Android ו-iOS) פלט ואחסון --directories-to-pull --paths-to-pull רשימה של נתיבים שצריך לשלוף מהמכשיר אחרי ההפעלה (DEVICE_PATH ב-Android,‏ BUNDLE_ID:DEVICE_PATH ב-iOS).
‫Android נפוץ פרמטרים ונכסים עיקריים --app --apps רשימה. אם יש כמה קובצי APK או AAB של האפליקציה, צריך להעביר את כולם אל --apps.
‫Android נפוץ פרמטרים ונכסים עיקריים --additional-apks --apps רשימה. מיזוג ערכים נוספים של רשימות ישירות לרשימה הראשית של --apps.
‫Android נפוץ פרמטרים ונכסים עיקריים --obb-files --other-files-to-push מילון בפורמט SOURCE=DEST. מעבירים קובצי OBB ישירות לנתיב המכשיר (/sdcard/Android/obb/{package_name}/).
‫Android נפוץ הגדרה וטירגוט של מכשירים --device locale={L} --locale={L} ממפה את הגדרות המכשיר לדגל --locale ברמה העליונה (language-region, למשל --locale=en-US).
‫Android נפוץ הגדרה וטירגוט של מכשירים --device orientation={O} --orientation={O} ממפה את כיוון המכשיר לדגל --orientation ברמה העליונה (portrait או landscape).
‫Android נפוץ הגדרה וטירגוט של מכשירים לא רלוונטי --coordinates קואורדינטות של הדמיית מיקום (latitude,longitude, לדוגמה, 37.4220,-122.0841).
‫Android נפוץ בקרה על ביצוע בקשות ובעיות של חוסר יציבות --grant-permissions ברירת מחדל אוטומטית אוטומטיות. הרשאות בתחילת ההפעלה ניתנות באופן אוטומטי כברירת מחדל (שווה ערך ל---grant-permissions=all).|
‫Android נפוץ פלט ואחסון לא רלוונטי --dumpsys אוספים dumpsys מהמכשיר (always או on-failure).
‫Android נפוץ פלט ואחסון לא רלוונטי --bugreport אוספים דוח על הבאג מהמכשיר (always או on-failure).
Android Instrumentation פרמטרים ונכסים עיקריים --type=instrumentation sessions submit instrumentation מבנה פקודת המשנה קובע את סוג הבדיקה במקום דגל --type.
Android Instrumentation פרמטרים ונכסים עיקריים --test --test הנתיב לקובץ הבינארי שמכיל את בדיקות האינסטרומנטציה.
Android Instrumentation בקרה על ביצוע בקשות ובעיות של חוסר יציבות --timeout --instrumentation-timeout משך הזמן (למשל, ‫10m, 20s, 1h). טווח תקין: 1m עד 3h (ברירת המחדל היא 5m).
Android Instrumentation בקרה על ביצוע בקשות ובעיות של חוסר יציבות לא רלוונטי --flaky-test-parallel-retry בוליאני. אם לנסות שוב שגיאות בדיקה במקביל (ברירת המחדל היא ברצף).
Android Instrumentation בקרה על ביצוע בקשות ובעיות של חוסר יציבות לא רלוונטי --flaky-test-retry-level מחרוזת. רמת הניסיון החוזר: shard או test (ברירת המחדל היא shard).
Android Instrumentation מריץ בדיקות ויעדים --test-runner-class --test-runner-class מחלקה מוגדרת במלואה של מריץ הבדיקות.
Android Instrumentation מריץ בדיקות ויעדים --test-targets --test-targets מילון שתומך במפתחות כמו package,‏ notPackage,‏ class,‏ notClass,‏ annotation,‏ notAnnotation ו-size. פורמטים כמו testfile או notTestfile לא נתמכים.
Android Instrumentation מריץ בדיקות ויעדים --use-orchestrator --orchestrator-version מקבל את הערך auto (כלי התזמור שמוגדר כברירת מחדל) או מחרוזת של גרסה ספציפית (למשל, 1.6).
Android Instrumentation מריץ בדיקות ויעדים --environment-variables --additional-test-options מילון של אפשרויות שמועברות לכלי להרצת בדיקות. אסור להשתמש כאן בפורמטים שנתמכים ב---test-targets.
iOS נפוץ פרמטרים ונכסים עיקריים --additional-ipas --additional-apps רשימה של קובצי .ipa שצריך להתקין במכשיר לפני הרצת הבדיקה.
iOS XCTest בלבד פרמטרים ונכסים עיקריים --type=xctest sessions submit xctest מבנה פקודת המשנה קובע את סוג הבדיקה במקום הדגל --type (משתמש ב-gcloud alpha).
iOS XCTest בלבד פרמטרים ונכסים עיקריים --test --test הנתיב לקובץ ה-ZIP שמכיל את האפליקציה ל-iOS ואת קובצי ה-XCTest.
iOS XCTest בלבד בקרה על ביצוע בקשות ובעיות של חוסר יציבות --timeout --xctest-timeout משך הזמן המקסימלי המותר להרצת XCTest (טווח חוקי: 1m עד 1h, ברירת המחדל היא 5m).
iOS XCTest בלבד מריץ בדיקות ויעדים --xctestrun-file --xctestrun-file הנתיב לקובץ ‎ .xctestrun בהתאמה אישית.
iOS XCTest בלבד מריץ בדיקות ויעדים --xcode-version --xcode-version מזהה הקטלוג או מחרוזת הגרסה של Xcode שבהם רוצים להשתמש (למשל, xcode-16-4 או 16.4). אפשר לשלוח שאילתה באמצעות software-versions list.

הנחיות מעשיות לתרגום

כדי להמיר את ההגדרות של Firebase Test Lab ו-Flank להרצה במכשיר, פועלים לפי ההנחיות הבאות:

1. מפרט המכשיר

ב-gcloud beta device-run, --device מקבלת רשימה מופרדת בפסיקים של מחרוזות מזהה של מודל וגרסה. בניגוד ל-Firebase, שבה נדרש דגל --device אחד לכל מכשיר, הרצה במכשיר מאפשרת לציין כמה מכשירים בדגל אחד. השפה, הכיוון והקואורדינטות המדומות של המכשיר מצוינים באמצעות דגלים נפרדים ברמה העליונה:

  • ❌ --device model=MediumPhone.arm,version=32,locale=en,orientation=portrait
  • ✅ --device=mediumphone-arm-32 --locale=en-US --orientation=portrait

2. מילונים ורשימות

המרת דגלים שמופרדים בפסיקים לרשימות (--apps, --paths-to-pull) או למילונים של מפתח/ערך (--other-files-to-push, --additional-test-options):

  • ❌ --other-files /sdcard/file1.txt=local/file1.txt,/sdcard/file2.txt=local/file2.txt
  • ✅ --other-files-to-push local/file1.txt=/sdcard/file1.txt,local/file2.txt=/sdcard/file2.txt

3. שיטות חלוקה לפלחים (sharding)

  • פיצול אחיד:
    • מגדירים את --sharding-option=uniform.
    • מגדירים את --uniform-sharding-count={count} (1-20 למכשירים פיזיים, 1-200 למכשירים וירטואליים; ב-iOS יש רק מכשירים פיזיים).
  • חלוקה חכמה למקטעים:
    • מגדירים את --sharding-option=smart.
    • מגדירים את --smart-sharding-target-duration={duration} (למשל, ‫2m, 10m, 1h; טווח תקין: 2m עד 1h).
    • מגדירים את --smart-sharding-record-name={record_name} (מצביע על רשומת המעקב של YAML בתוך --bucket-name בקטע automation/smart-sharding/).
    • מגדירים את --smart-sharding-max-shard-count={max_count} (מגבלה מקסימלית אופציונלית: 0-20 למכשירים פיזיים, 0-200 למכשירים וירטואליים; ב-iOS יש רק מכשירים פיזיים).

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

  • אסינכרוני והמתנה: כשמציינים את --async, ה-CLI מחזיר מיד את מזהה הסשן שנוצר. אפשר להמתין להשלמת הסשן בתהליכי עבודה של CI/CD באמצעות: gcloud beta device-run sessions wait <SESSION_ID>

5. הגדרת YAML דקלרטיבית (--flags-file)

אם אתם משתמשים בהגדרות מורכבות או עובדים בצוותים שמעדיפים לתחזק קבצים עם ניהול גרסאות במקום פקודות ארוכות בטרמינל, gcloud מספק מעבד מקדים אוניברסלי של ארגומנטים ב---flags-file (ראו $ gcloud topic flags-file):

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

!NOTE למה המפתחות צריכים את --: gcloud מוסיף מפתחות YAML ישירות למנתח ה-CLI כדגלים של שורת הפקודה. כל מפתח בקובץ ה-YAML צריך להתחיל ב--- (למשל, --device:, --apps:). בלי --, הפקודה gcloud דוחה אותם כארגומנטים לא מזוהים לפי מיקום.

הנה דוגמה שממחישה דגלים של רשימות ומילונים עם ערכים מרובים:

# device-run-flags.yaml
--device:
  -   mediumphone-arm-32
  -   shiba-36
--apps:
  -   app-debug.apk
  -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
  -   /sdcard/screenshots
  -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

דוגמאות לתרגומים

אתם יכולים להשתמש בדוגמאות האלה כדי לתרגם את ההגדרות הקיימות של Firebase Test Lab ו-Flank להרצה במכשיר.

מ-Firebase Test Lab להרצה במכשיר

firebase cmd:

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables coverage=true

התרגום:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options coverage=true

הגדרות Flank להרצה במכשיר

flank options (flank.yml):

gcloud:
  app: app-debug.apk
  test: app-debug-androidTest.apk
  device:
    -   model: mediumphone-arm
      version: 32
  shard-time: 120
  smart-flank-gcs-path: gs://my-bucket/automation/smart-sharding/timing-record.yaml

התרגום:

תרגום ישיר לפקודת ה-CLI המודרנית:

gcloud beta device-run sessions submit instrumentation \
  --device=mediumphone-arm-32 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

אפשרות 2: קובץ דגלים דקלרטיבי בפורמט YAML‏ (--flags-file)

אם אתם מעדיפים לנהל את ההגדרות בקובץ YAML עם ניהול גרסאות במקום במחרוזות של סקריפט מעטפת, אתם יכולים להשתמש בתכונה המובנית של gcloud,‏ --flags-file:

# device-run-flags.yaml
# Note: gcloud requires keys to start with '--'
--device:
  -   mediumphone-arm-32
--apps:
  -   app-debug.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record

שליחה באמצעות CLI:

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

(אפשר גם להוסיף או לשנות דגלים בשורת הפקודה, למשל להוסיף את --async).

גילוי קטלוג המכשירים

listing & inspecting devices:

# List all available Android devices
gcloud beta device-run devices list --filter="platform:android"

# Filter devices with high fleet capacity (replaces legacy list-device-capacities)
gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH"

# Describe a specific device (OS versions, form factors, orientation, locales, capacity)
gcloud beta device-run devices describe redfin-30

מחזור חיים של סשן מקצה לקצה ב-CI/CD

submitting, waiting, and inspecting sessions:

# 1. Submit asynchronously and capture session ID
SESSION_ID=$(gcloud beta device-run sessions submit instrumentation \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device=mediumphone-arm-32 \
  --async \
  --format="value(name)")

# 2. Wait for session completion in CI/CD pipeline
gcloud beta device-run sessions wait "$SESSION_ID"

# 3. Describe session summary (or pass --full for complete details)
gcloud beta device-run sessions describe "$SESSION_ID"

# 4. Cancel a running session if aborted
gcloud beta device-run sessions cancel "$SESSION_ID"