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

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

כלי שורת הפקודה ומשימות Gradle שמתוארים בדף הזה לא תלויים בערכת הכלים לממשק המשתמש. אם אתם רוצים לכתוב בדיקות של ממשק המשתמש ל-Compose, עיינו במאמר בדיקת פריסת פיתוח נייטיב. אחרי שכותבים את הבדיקות, ממשיכים עם המדריך הזה כדי להריץ אותן מהטרמינל או מסביבת האינטגרציה הרציפה (CI) המרוחקת.

כשאתם יוצרים את האפליקציה באמצעות מערכת ה-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/ ספרייה.

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

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

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

קובצי תוצאות של בדיקת 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‏ (ADB), יש יותר אפשרויות לבחירת הבדיקות להרצה מאשר בכל שיטה אחרת. אתם יכולים לבחור שיטות בדיקה ספציפיות, לסנן בדיקות לפי הערה מותאמת אישית או לציין אפשרויות בדיקה. מכיוון שהרצת הבדיקה נשלטת לחלוטין משורת הפקודה, אפשר להתאים אישית את הבדיקה באמצעות סקריפטים של מעטפת בדרכים שונות.

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

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

כדי להריץ בדיקה עם 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 שבה אתם משתמשים. שם החבילה ב-Android הוא הערך של מאפיין החבילה של רכיב המניפסט בקובץ המניפסט של חבילת הבדיקה (AndroidManifest.xml).

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

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

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

דגלי am instrument

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

טבלה 2. דגלים חשובים am instrument

דגל ערך תיאור
-w (ללא) האפשרות הזו מאלצת את am instrument להמתין עד שהאינסטרומנטציה תסתיים לפני שהיא תסתיים בעצמה. הפקודה הזו משאירה את המעטפת פתוחה עד שהבדיקות מסתיימות. הדגל הזה נדרש כדי לראות את תוצאות הבדיקות.
-r (ללא) התוצאות מוצגות בפורמט גולמי. משתמשים בדגל הזה כשרוצים לאסוף מדידות של ביצועים כדי שהן לא יעוצבו כתוצאות בדיקה. הדגל הזה מיועד לשימוש עם הדגל -e perf true (שמתואר בקטע אפשרויות של כלי am).
-e <test_options> מספק אפשרויות בדיקה כצמדי מפתח/ערך. הכלי am instrument מעביר את הנתונים האלה למחלקת המכשור שצוינה באמצעות השיטה onCreate(). אפשר לציין כמה מקרים של -e <test_options>. המפתחות והערכים מתוארים בקטע אפשרויות של כלי am. אפשר להשתמש בצמדי מפתח/ערך האלה רק עם AndroidJUnitRunner. השימוש בהם עם כיתות אחרות לא משפיע.
--no-hidden-api-checks (ללא) ההגבלות על השימוש בממשקי API מוסתרים מושבתות. מידע נוסף על ממשקי API מוסתרים ועל ההשפעה שלהם על האפליקציה זמין במאמר הגבלות על ממשקים שאינם SDK.

אמצעי תשלום

הכלי 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 לשימוש עם כלי הרצת הבדיקות

מפתח ערך תיאור
package <Java_package_name> שם החבילה המלא של Java לאחת מהחבילות באפליקציית הבדיקה. כל מחלקת מקרה בדיקה שמשתמשת בשם החבילה הזה מופעלת. שימו לב שזה לא שם חבילה של Android. לחבילת בדיקה יש שם חבילה אחד של Android, אבל יכולות להיות בה כמה חבילות Java.
class <class_name> שם המחלקה המלא ב-Java של אחת מהמחלקות של מקרה הבדיקה. רק מחלקת מקרה הבדיקה הזו מופעלת.
<class_name>#method name שם מחלקה של מקרה בדיקה שמוגדר במלואו ואחת מהשיטות שלה. רק השיטה הזו מופעלת. שימו לב לסימן הסולמית (#) בין שם המחלקה לשם ה-method.
size [small | medium | large] מריץ שיטת בדיקה עם הערה לפי גודל. ההערות הן @SmallTest, ‏@MediumTest ו-@LargeTest.
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

תרחישים נוספים לדוגמה מפורטים במאמרי העזרה של ה-API של AndroidJUnitRunner.

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

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

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

  • פלאגין של Android Gradle בגרסה ‎9.5.0-alpha05 ואילך.

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

היקף הדוח פקודה תיאור דיווח על מיקום
המודול הנוכחי ./gradlew :module_name:testAllSuites --continue יוצר דוח בדיקה מאוחד למודול הנוכחי, וממזג את התוצאות של בדיקת היחידה ובדיקת אינסטרומנטציה. path_to_your_project/module_name/build/reports/testAllSuites/test-report/
המודול הנוכחי ויחסי התלות ./gradlew :module_name:testAllSuitesWithDependencies --continue יוצר דוח בדיקה מאוחד למודול הנוכחי ולתלות בספרייה שלו, ומשלב את תוצאות הבדיקות של היחידה ובדיקת אינסטרומנטציה. path_to_your_project/module_name/build/reports/testAllSuitesWithDependencies/test-report/