בדיקה משורת הפקודה

במאמר הזה מוסבר איך להריץ בדיקות ישירות משורת הפקודה. במסמך הזה מניחים שכבר יודעים איך ליצור אפליקציית Android ואיך לכתוב בדיקות לאפליקציה. מידע נוסף על בניית בדיקות לאפליקציה זמין במאמר בדיקת אפליקציות ב-Android.

כשמבצעים build לאפליקציה באמצעות מערכת ה-build של Gradle, התוסף Android Gradle מאפשר להריץ בדיקות מפרויקט Gradle באמצעות שורת הפקודה. כדי לקבל שליטה מדויקת יותר, אפשר להריץ את הבדיקות באמצעות מעטפת Android Debug Bridge‏ (adb). האפשרות הזו שימושית כשמריצים בדיקות בסביבת אינטגרציה רציפה.

במאמר הרחבת הבדיקות עם מכשירים בניהול Gradle מוסבר איך להריץ בדיקות אינסטרומנטציה אוטומטיות משורת הפקודה באמצעות מכשירים וירטואליים שמנוהלים על ידי Gradle.

הרצת בדיקות באמצעות Gradle

הפלאגין של Android Gradle מאפשר להריץ בדיקות מפרויקט Gradle באמצעות שורת הפקודה.

בטבלה שלמטה מוסבר איך מריצים את הבדיקות באמצעות Gradle:

טבלה 1. דרכים שונות להרצת בדיקות באמצעות Gradle

סוג בדיקת היחידה הפקודה להרצה המיקום של תוצאת הבדיקה
בדיקת יחידה מקומית מריצים את המשימה test: 

./gradlew test
קבצים של תוצאות בדיקה ב-HTML:
path_to_your_project/module_name/build/reports/tests/ directory.

קובצי תוצאות של בדיקת XML:‏
path_to_your_project/module_name/build/test-results/ directory.

בדיקת יחידה עם אינסטרומנטציה מריצים את המשימה connectedAndroidTest: 

./gradlew connectedAndroidTest
קבצים של תוצאות בדיקה ב-HTML:
path_to_your_project/module_name/build/reports/androidTests/connected/ directory.

קובצי תוצאות של בדיקת XML:‏
path_to_your_project/module_name/build/outputs/androidTest-results/connected/ directory.

‫Gradle תומך בקיצורים של שמות משימות. לדוגמה, אפשר להפעיל את המשימה connectedAndroidTest על ידי הזנת הפקודה הבאה:

./gradlew cAT

אפשר גם להריץ את משימות Gradle‏ check ו-connectedCheck. המשימות האלה מריצות את הבדיקות המקומיות או את הבדיקות עם מכשור, בהתאמה, אבל כוללות בדיקות אחרות שנוספו על ידי פלאגינים אחרים של Gradle.

הרצת בדיקות במודול

המשימות test ו-connectedAndroidTest מריצות בדיקות בכל מודול בפרויקט. אפשר להריץ בדיקות במודול ספציפי על ידי הוספת שם המודול ונקודתיים (:) לפני המשימה test או connectedAndroidTest. לדוגמה, הפקודה הבאה מריצה בדיקות עם מכשור רק למודול mylibrary:

./gradlew mylibrary:connectedAndroidTest

הרצת בדיקות בווריאנט build

המשימות test ו-connectedAndroidTest מריצות בדיקות על כל וריאנט build בפרויקט. אפשר לטרגט וריאנט build ספציפי באמצעות התחביר הבא:

  • לבדיקות יחידה מקומיות: 
    ./gradlew testVariantNameUnitTest
  • בבדיקות עם מכשור: 
    ./gradlew connectedVariantNameAndroidTest

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

כשמריצים בדיקות יחידה מקומיות, אפשר לטרגט בדיקות ספציפיות באמצעות הדגל --tests ב-Gradle. לדוגמה, הפקודה הבאה מריצה רק את הבדיקות sampleTestMethod עבור וריאציית ה-build שצוינה. מידע נוסף על השימוש בדגל --tests זמין במאמר בנושא סינון בדיקות במאמרי העזרה של Gradle.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

הרצת בדיקות באמצעות adb

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

כדי להריץ בדיקה משורת הפקודה, מריצים את הפקודה adb shell כדי להפעיל מעטפת של שורת פקודה במכשיר או באמולטור. בתוך המעטפת הזו אפשר ליצור אינטראקציה עם מנהל הפעילות באמצעות הפקודה am ולהשתמש בפקודת המשנה instrument כדי להריץ את הבדיקות.

כקיצור דרך, אפשר להפעיל adb shell, להתקשר אל am instrument ולציין את ההתרעות לגבי שורת הפקודה, והכול בשורת קלט אחת. המעטפת נפתחת במכשיר או באמולטור, מריצה את הבדיקות, יוצרת פלט ואז חוזרת לשורת הפקודה במחשב.

כדי להריץ בדיקה באמצעות am instrument:

  1. יוצרים או יוצרים מחדש את האפליקציה הראשית ואת חבילת הבדיקה.
  2. מתקינים את חבילת הבדיקה ואת קובצי חבילת Android (קובצי APK) של האפליקציה הראשית במכשיר Android הנוכחי או באמולטור.

  3. בשורת הפקודה, מזינים:

    adb shell am instrument -w <test_package_name>/<runner_class>

    כאשר <test_package_name> הוא שם החבילה ב-Android של אפליקציית הבדיקה, ו-<runner_class> הוא השם של מחלקת Android test runner שבה אתם משתמשים. שם החבילה ב-Android הוא הערך של מאפיין החבילה באלמנט המניפסט בקובץ המניפסט של חבילת הבדיקה (AndroidManifest.xml).

    המחלקות של Android test runner הן בדרך כלל AndroidJUnitRunner:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

תוצאות הבדיקה יופיעו ב-STDOUT.

am instrument flags

כדי לראות רשימה של כל האפשרויות לשימוש בפקודה am instrument, מריצים את הפקודה adb shell am help. בטבלה הבאה מפורטים כמה דגלים חשובים:

טבלה 2. מתגי am instrument feature flag חשובים

סימון ערך תיאור
-w (ללא) מאפשר ל-am instrument להמתין עד שהאינסטרומנטציה תסיים את הפעולה לפני שהוא עצמו יסיים את הפעולה. הפעולה הזו משאירה את המעטפת פתוחה עד שהבדיקות מסתיימות. הדגל הזה נדרש כדי לראות את תוצאות הבדיקות.
-r (ללא) התוצאות מוצגות בפורמט גולמי. משתמשים בדגל הזה כשרוצים לאסוף מדידות של ביצועים כך שהן לא יעוצבו כתוצאות בדיקה. הדגל הזה מיועד לשימוש עם הדגל -e perf true (שמתואר בקטע אפשרויות של כלי am).
-e <test_options> מספק אפשרויות בדיקה כצמדי מפתח/ערך. ‫The am instrument tool passes these to the specified instrumentation class using its onCreate() method. אפשר לציין כמה מקרים של -e <test_options>. המפתחות והערכים מתוארים בקטע אפשרויות של כלי am. אפשר להשתמש בצמדי המפתח/ערך האלה רק עם AndroidJUnitRunner או עם InstrumentationTestRunner ומחלקות המשנה שלו. השימוש בהם עם כיתות אחרות לא משפיע.
--no-hidden-api-checks (ללא) ההגבלות על השימוש בממשקי API מוסתרים מושבתות. מידע נוסף על ממשקי API מוסתרים ועל ההשפעה שלהם על האפליקציה זמין במאמר הגבלות על ממשקי SDK שאינם ממשקי API.

אפשרויות של אמצעי תשלום

הכלי am instrument מעביר אפשרויות בדיקה אל AndroidJUnitRunner או אל InstrumentationTestRunner בצורה של צמדי מפתח/ערך, באמצעות הדגל -e, עם התחביר הבא:

-e <key> <value>

חלק מהמפתחות יכולים לקבל כמה ערכים. מציינים כמה ערכים ברשימה מופרדת בפסיקים. לדוגמה, הקריאה הבאה של AndroidJUnitRunner מספקת כמה ערכים למפתח package:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

בטבלה הבאה מפורטים צמדי מפתח/ערך שאפשר להשתמש בהם עם כלי ההרצה של הבדיקות:

טבלה 3. ‫‎-e flag key-value pairs to use with your test runner

מפתח ערך תיאור
package <Java_package_name> שם החבילה המוגדר במלואו של Java לאחת מהחבילות באפליקציית הבדיקה. כל מחלקת תרחישי הבדיקה שמשתמשת בשם החבילה הזה מופעלת. שימו לב שזה לא שם חבילה של Android. לחבילת בדיקה יש שם חבילה אחד של Android, אבל היא יכולה לכלול כמה חבילות Java.
class <class_name> שם המחלקה המוגדר במלואו ב-Java של אחת מהמחלקות של מקרה הבדיקה. רק המחלקה הזו של מקרה הבדיקה מופעלת.
<class_name>#method name שם מחלקה של תרחיש בדיקה שמוגדר במלואו ואחת מהשיטות שלה. רק השיטה הזו מופעלת. שימו לב לסולמית (#) בין שם המחלקה לבין שם ה-method.
func true מריץ את כל מחלקות הבדיקה שמרחיבות את InstrumentationTestCase.
unit true מריץ את כל מחלקות הבדיקה שלא מרחיבות את InstrumentationTestCase או את PerformanceTestCase.
size [small | medium | large] מריצה שיטת בדיקה עם הערה לגבי הגודל. ההערות הן @SmallTest,‏ @MediumTest ו-@LargeTest.
perf true מריץ את כל מחלקות הבדיקה שמטמיעות את PerformanceTestCase. כשמשתמשים באפשרות הזו, צריך לציין את הדגל -r עבור am instrument כדי שהפלט יישמר בפורמט גולמי ולא יפורמט מחדש כתוצאות בדיקה.
debug true מריץ בדיקות במצב ניפוי באגים.
log true טוען את כל הבדיקות שצוינו ומתעד אותן ביומן, אבל לא מריץ אותן. פרטי הבדיקה מופיעים בSTDOUT. אפשר להשתמש בזה כדי לאמת שילובים של מסננים אחרים ומפרטי בדיקה.
emma true מריץ ניתוח של רמת הכיסוי של הקוד של EMMA וכותב את הפלט ל-/data/<app_package>/coverage.ec במכשיר. כדי לשנות את מיקום הקובץ, משתמשים במפתח coverageFile שמתואר ברשומה הבאה.

הערה: כדי להשתמש באפשרות הזו, צריך ליצור גרסה של אפליקציית הבדיקה עם מכשור EMMA, שאפשר ליצור באמצעות יעד coverage.

coverageFile <filename> ההגדרה הזו מבטלת את מיקום ברירת המחדל של קובץ הכיסוי של EMMA במכשיר. מציינים את הערך הזה כנתיב ושם קובץ בפורמט UNIX. שם הקובץ שמוגדר כברירת מחדל מתואר ברשומה של המפתח emma.

כשמשתמשים בדגל -e, חשוב לשים לב לדברים הבאים:

  • ‫am instrument מפעיל את onCreate(Bundle) עם Bundle שמכיל את צמדי המפתח/ערך.
  • המפתח package מקבל עדיפות על פני המפתח class. אם מציינים חבילה ואז מציינים בנפרד מחלקה בתוך החבילה הזו, מערכת Android מריצה את כל הבדיקות בחבילה ומתעלמת ממפתח המחלקה.
  • המפתח func והמפתח unit הם בלעדיים.

דוגמאות לשימוש

בקטעים הבאים מפורטות דוגמאות לשימוש בפקודה am instrument להרצת בדיקות. המבנה שלהם הוא כזה:

  • שם החבילה ב-Android של חבילת הבדיקה הוא com.android.demo.app.tests.
  • שני קלאסים של בדיקות עם מכשור:
    • ‫TestClass1, שמכיל את שיטת הבדיקה testMethod1.
    • ‫TestClass2, שמכיל את שיטות הבדיקה testMethod2 ו-testMethod3.
  • הכלי להרצת הבדיקות הוא AndroidJUnitRunner.

הרצת כל חבילת הבדיקה

כדי להריץ את כל מחלקות הבדיקה בחבילת הבדיקה, מזינים:

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

הרצת כל הבדיקות בכיתת מקרה בדיקה

כדי להריץ את כל הבדיקות בכיתה TestClass1, מזינים:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

בחירת קבוצת משנה של בדיקות

כדי להריץ את כל הבדיקות במחלקה TestClass1 ואת ה-method‏ testMethod3 ב-TestClass2, מזינים:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

AndroidJUnitRunner במאמר בנושא הפניית API מופיעים תרחישי שימוש נוספים.

הצגת דוחות בדיקה מאוחדים

הפלאגין של Android Gradle מספק משימות מאוחדות של דוחות בדיקה, שיוצרות לוחות בקרה ב-HTML שמשלבים תוצאות מבדיקות יחידה ומבדיקות עם מכשור.

דרישות מוקדמות

  • פלאגין של Android Gradle‏ ‎9.2.0-alpha07 ומעלה.

כדי ליצור דוחות בדיקה מאוחדים, מריצים אחת מהמשימות הבאות:

היקף הדוח פקודה תיאור דיווח על מיקום
המודול הנוכחי ./gradlew :module_name:createTestReport יוצר דוח בדיקה מאוחד למודול הנוכחי, ומשלב את התוצאות של בדיקות היחידה ובדיקות האינסטרומנטציה. path_to_your_project/module_name/build/reports/tests/test-report/
המודול הנוכחי ויחסי התלות ./gradlew :module_name:createAggregatedTestReport יוצר דוח בדיקה מאוחד למודול האפליקציה הנוכחי ולתלות שלו בספריות. path_to_your_project/module_name/build/reports/tests/aggregated-test-report/