הסקיל הזה עוזר לתרגם תהליכי עבודה והגדרות קודמות של הרצת בדיקות (מ-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
התרגום:
אפשרות 1: הפעלה ישירה של CLI (מומלץ)
תרגום ישיר לפקודת ה-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"