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

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

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

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

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

קובצי תוצאות של בדיקת 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 היא 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

דגל ערך תיאור
-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 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.
size [small | medium | large] מריצה שיטת בדיקה עם הערה של גודל. ההערות הן @SmallTest,‏ @MediumTest ו-@LargeTest.
debug true מריץ בדיקות במצב ניפוי באגים.
log true טוען את כל הבדיקות שצוינו ומתעד אותן ביומן, אבל לא מריץ אותן. פרטי הבדיקה מופיעים בSTDOUT. אפשר להשתמש בזה כדי לאמת שילובים של מסננים אחרים ומפרטי בדיקה.
emma true מריץ ניתוח של רמת הכיסוי של הקוד EMMA וכותב את הפלט אל /data/<app_package>/coverage.ec במכשיר. כדי לשנות את מיקום הקובץ, משתמשים במפתח coverageFile שמתואר ברשומה הבאה.

הערה: כדי להשתמש באפשרות הזו, צריך ליצור גרסת build של אפליקציית הבדיקה עם מכשור 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 ובשיטה 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/