הרצת בדיקות (atest)

Atest הוא כלי שורת פקודה שמאפשר למשתמשים ליצור, להתקין ולהריץ בדיקות של Android באופן מקומי. כך אפשר להאיץ מאוד את ההרצות החוזרות של הבדיקות בלי צורך בידע לגבי אפשרויות שורת הפקודה של Trade Federation test harness. בדף הזה מוסבר איך משתמשים ב-Atest כדי להריץ בדיקות ל-Android.

למידע כללי על כתיבת בדיקות ל-Android, תוכלו לעיין במאמר בדיקת פלטפורמת Android.

מידע על המבנה הכללי של Atest זמין במדריך למפתחים של Atest.

מידע על הפעלת בדיקות בקובצי TEST_MAPPING דרך Atest זמין במאמר הפעלת בדיקות בקובצי TEST_MAPPING.

כדי להוסיף תכונה ל-Atest, פועלים לפי תהליך העבודה של מפתחים ב-Atest.

הגדרת הסביבה

כדי להגדיר את סביבת Atest לפי ההוראות שמפורטות במאמרים הגדרת הסביבה, בחירת יעד ויצירת הקוד.

שימוש בסיסי

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

atest test-to-run [optional-arguments]

ארגומנטים אופציונליים

בטבלה הבאה מפורטים הארגומנטים הנפוצים ביותר. הרשימה המלאה זמינה דרך atest --help.

אפשרות אפשרות ארוכה תיאור
-b --build יצירת יעדי בדיקה. (ברירת מחדל)
-i --install התקנת פריטי מידע שנוצרים בתהליך פיתוח (APK) במכשיר. (ברירת מחדל)
-t --test הרצת הבדיקות. (ברירת מחדל)
-s --serial הרצת הבדיקות במכשיר שצוין. אפשר לבדוק רק מכשיר אחד בכל פעם.
-d --disable-teardown משבית את הריסת הבדיקה ואת הניקוי שלה.
--dry-run הרצת Atest ללא יצירה, התקנה או הפעלה של בדיקות בפועל.
-m --rebuild-module-info מאלץ בנייה מחדש של הקובץ module-info.json.
-w --wait-for-debugger בהמתנה שהכלי לניפוי באגים יסתיים לפני הריצה.
-v --verbose הצגת רישום ביומן ברמה DEBUG.
--iterations הבדיקה תרוץ בלולאה עד שמגיעים לחזרה (iteration) המקסימלית. (10 כברירת מחדל)
--rerun-until-failure [COUNT=10] מריץ מחדש את כל הבדיקות עד שמתרחש כשל או עד שמגיעים לאיטרציה המקסימלית. (10 כברירת מחדל)
--retry-any-failure [COUNT=10] מריץ שוב בדיקות שנכשלו עד שהוא עובר או מגיע איטרציה מקסימלית. (10 כברירת מחדל)
--start-avd המערכת יוצרת AVD באופן אוטומטי ומריצה בדיקות במכשיר הווירטואלי.
--acloud-create יצירת AVD באמצעות הפקודה acloud.
--[CUSTOM_ARGS] מציין ארגומנטים מותאמים אישית למפעילי הבדיקות.
-a --all-abi הפעלת הבדיקות לכל ארכיטקטורות המכשירים הזמינות.
--host הרצת הבדיקה באופן מלא במארח ללא מכשיר.
הערה: הרצת בדיקה של מארח שמחייבת מכשיר עם --host תיכשל.
--history הצגת תוצאות הבדיקה בסדר כרונולוגי.
--latest-result הדפסת תוצאת הבדיקה האחרונה.

מידע נוסף על -b,‏ -i ו--t זמין בקטע ציון שלבים: build,‏ install או run.

ציון בדיקות

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

  • שם המודול
  • מודול:Class
  • שם הכיתה
  • בדיקת שילוב של Tradefed
  • נתיב הקובץ
  • שם חבילה

יש להפריד הפניות לבדיקות מרובות באמצעות רווחים, באופן הבא:

atest test-identifier-1 test-identifier-2

שם המודול

כדי להריץ מודול בדיקה שלם, משתמשים בשם המודול שלו. מזינים את השם כפי שהוא מופיע במשתנים LOCAL_MODULE או LOCAL_PACKAGE_NAME בקובץ Android.mk או Android.bp של הבדיקה.

לדוגמה:

atest FrameworksServicesTests
atest CtsVideoTestCases

מודול:Class

כדי להפעיל כיתה אחת בתוך מודול, משתמשים ב-Module:Class. מודול זהה לזה שמתואר בקטע שם המודול. Class הוא השם של כיתת הבדיקה בקובץ .java, והוא יכול להיות השם המלא של הכיתה או השם הבסיסי.

לדוגמה:

atest CtsVideoTestCases:VideoEncoderDecoderTest
atest FrameworksServicesTests:ScreenDecorWindowTests
atest FrameworksServicesTests:com.android.server.wm.ScreenDecorWindowTests

שם הכיתה

כדי להריץ מחלקה אחת בלי לציין במפורש את שם המודול, משתמשים בשם המחלקה.

לדוגמה:

atest ScreenDecorWindowTests
atest VideoEncoderDecoderTest

בדיקת שילוב של Tradefed

כדי להריץ בדיקות שמשולבות ישירות ב-TrendFed (ללא מודולים), צריך להזין את השם כפי שהוא מופיע בפלט של הפקודה tradefed.sh list configs. לדוגמה:

כדי להריץ את הבדיקה reboot.xml:

atest example/reboot

כדי להריץ את הבדיקה native-benchmark.xml:

atest native-benchmark

נתיב הקובץ

אפשר להריץ ב-Atest גם בדיקות מבוססות-מודול וגם בדיקות מבוססות-שילוב, על ידי הזנת הנתיב לקובץ הבדיקה או לספריית הבדיקה שלהם בהתאם. אפשר גם להריץ כיתה אחת על ידי ציון הנתיב לקובץ Java של הכיתה. יש תמיכה גם בנתיבים יחסיים וגם בנתיבים מוחלטים.

הפעלת מודול

בדוגמאות הבאות מפורטות שתי דרכים להפעלת המודול CtsVideoTestCases באמצעות נתיב קובץ.

מריצים מ-Android repo-root:

atest cts/tests/video

מריצים מ-Android repo-root/cts/tests/video:

    atest .

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

הדוגמה הבאה מראה איך להריץ מחלקה ספציפית בתוך המודול CtsVideoTestCases באמצעות נתיב קובץ.

מ-Android repo-root:

    atest cts/tests/video/src/android/video/cts/VideoEncoderDecoderTest.java

הרצת בדיקת אינטגרציה

בדוגמה הבאה מוסבר איך להריץ בדיקת שילוב באמצעות נתיב קובץ מ-Android repo-root:

    atest tools/tradefederation/contrib/res/config/example/reboot.xml

שם חבילה

Atest תומך בחיפוש בדיקות לפי שם חבילה.

לדוגמה:

    atest com.android.server.wm
    atest com.android.uibench.janktests

ציון השלבים: build,‏ install או run

משתמשים באפשרויות -b, -i ו--t כדי לציין אילו שלבים להריץ. אם לא מציינים אפשרות, כל השלבים יתבצעו.

  • יעדי build בלבד: atest -b test-to-run
  • הרצת בדיקות בלבד: atest -t test-to-run
  • התקנת קובץ ה-APK והרצת הבדיקות: atest -it test-to-run
  • פיתוח והרצה, בלי התקנה: atest -bt test-to-run

אימות יכול לאלץ בדיקה לדלג על שלב הניקוי או הפריקה. בדיקות רבות, כמו CTS, מנקות את המכשיר אחרי הרצת הבדיקה, כך שניסיון להריץ מחדש את הבדיקה עם -t נכשל ללא הפרמטר --disable-teardown. משתמשים ב--d לפני -t כדי לדלג על שלב הניקוי של הבדיקה ולבצע בדיקה אבולוציונית.

atest -d test-to-run
atest -t test-to-run

הרצה של שיטות ספציפיות

Atest תומך בהרצה של שיטות ספציפיות בתוך כיתה לבדיקה. אמנם צריך ליצור את המודול כולו, אבל כך מקצרים את הזמן הנדרש להרצת הבדיקות. כדי להריץ שיטות ספציפיות, מזהים את הכיתה באחת מהדרכים הנתמכות לזיהוי כיתה (Module:Class, נתיב קובץ וכו') ומצרפים את שם השיטה:

atest reference-to-class#method1

כשמציינים כמה שיטות, מפרידים ביניהן באמצעות פסיקים:

atest reference-to-class#method1,method2,method3

לדוגמה:

atest com.android.server.wm.ScreenDecorWindowTests#testMultipleDecors
atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval

בשתי הדוגמאות הבאות מוצגות הדרכים המועדפות להרצת שיטה אחת, testFlagChange. מומלץ להשתמש בדוגמאות האלה במקום להשתמש רק בשם הכיתה, כי ציון המודול או המיקום של קובץ ה-Java מאפשר ל-Atest למצוא את הבדיקה מהר יותר.

שימוש ב- Module:Class:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange

ממכשיר Android repo-root:

atest frameworks/base/services/tests/wmtests/src/com/android/server/wm/ScreenDecorWindowTests.java#testFlagChange

אפשר להריץ כמה שיטות ממחלקות וממודולים שונים:

atest FrameworksServicesTests:ScreenDecorWindowTests#testFlagChange,testRemoval ScreenDecorWindowTests#testMultipleDecors

להפעיל כמה כיתות

כדי להריץ כמה כיתות, צריך להפריד ביניהם באמצעות רווחים באותו אופן שבו מריצים כמה בדיקות. Atest יוצר ומריץ כיתות ביעילות, כך שציון קבוצת משנה של כיתות במודול משפרת את הביצועים בהשוואה להרצה של המודול כולו.

כדי להריץ שתי כיתות באותו מודול:

atest FrameworksServicesTests:ScreenDecorWindowTests FrameworksServicesTests:DimmerTests

כדי להריץ שתי כיתות במודולים שונים:

atest FrameworksServicesTests:ScreenDecorWindowTests CtsVideoTestCases:VideoEncoderDecoderTest

הרצת קובצי בינאריים של GTest

אפשר להריץ קובצי בינאריים של GTest באמצעות Atest. משתמשים ב--a כדי להריץ את הבדיקות האלה לכל ארכיטקטורות המכשירים הזמינות. בדוגמה הזו, הן armeabi-v7a (ARM 32 ביט) ו-arm64-v8a (ARM 64 ביט).

דוגמה לבדיקת קלט:

atest -a libinput_tests inputflinger_tests

כדי לבחור קובץ בינארי ספציפי של GTest להרצה, משתמשים בנקודתיים (:) כדי לציין את שם הבדיקה, ובתו hashtag (#) כדי לציין שיטה ספציפית.

לדוגמה, להגדרת הבדיקה הבאה:

TEST_F(InputDispatcherTest, InjectInputEvent_ValidatesKeyEvents)

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

atest inputflinger_tests:InputDispatcherTest

לחלופין, אפשר להריץ בדיקה ספציפית באמצעות: 

atest inputflinger_tests:InputDispatcherTest#InjectInputEvent_ValidatesKeyEvents

הרצת בדיקות ב-TEST_MAPPING

אפשר להריץ בדיקות בקבצים מסוג TEST_MAPPING באמצעות Atest.

הרצת בדיקות לפני שליחת בקשת תיקון באופן משתמע

מריצים בדיקות לפני שליחת קובץ בקבצים מסוג TEST_MAPPING בספרייה הנוכחית ובספריית ההורה:

atest

מריצים בדיקות לשליחה מראש של קובצי TEST_MAPPING בקובץ /path/to/project ובספריות ההורה שלו:

atest --test-mapping /path/to/project

הפעלת קבוצת בדיקה ספציפית

קבוצות הבדיקה הזמינות הן: presubmit(ברירת המחדל), postsubmit, mainline-presubmit ו-all.

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

atest :postsubmit

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

atest :all

מריצים בדיקות לאחר שליחת הקוד בקובצי TEST_MAPPING בתיקייה /path/to/project ובתיקיות ההורה שלה:

atest --test-mapping /path/to/project:postsubmit

מריצים בדיקות של השורה הראשית בקובצי TEST_MAPPING ב-/path/to/project ובספריות ההורה שלו:

atest --test-mapping /path/to/project:mainline-presubmit

הרצת בדיקות בספריות משנה

כברירת מחדל, Atest מחפש בדיקות רק בקובצי TEST_MAPPING כלפי מעלה (מהתיקייה הנוכחית או מהתיקייה שצוינה אל התיקיות ההורה שלה). אם רוצים להריץ בדיקות גם בקובצי TEST_MAPPING בתיקיות המשנה, צריך להשתמש ב---include-subdirs כדי לאלץ את Atest לכלול גם את הבדיקות האלה:

atest --include-subdirs /path/to/project

הרצת בדיקות במחזור

מריצים בדיקות באיטרציה על ידי העברת הארגומנט --iterations. בין שהבדיקה תעבור ובין שלא, Atest יחזור על הבדיקה עד שיגיע לחזרה המרבית.

לדוגמה:

כברירת מחדל, Atest חוזר על עצמו 10 פעמים. מספר החזרות חייב להיות מספר שלם חיובי.

atest test-to-run --iterations
atest test-to-run --iterations 5

הגישות הבאות עוזרות לזהות בקלות בדיקות לא יציבות:

גישה 1: מריצים את כל הבדיקות עד שמתרחשת כשל או שמגיעים לחזרה (iteration) המקסימלית.

  • הפסקה כשמתרחשת כשל או שהחזרה על הפעולה מגיעה לסיבוב ה-10 (ברירת המחדל). 
    atest test-to-run --rerun-until-failure
  • עוצרים כשמתרחשת כשל או שהחזרה על הפעולה מגיעה לסיבוב ה-100. 
    atest test-to-run --rerun-until-failure 100

גישה 2: מריצים רק בדיקות שנכשלו עד שמגיעים לאיטרציה המקסימלית או עד שמגיעים לאיטרציה המקסימלית.

  • נניח של-test-to-run יש כמה מקרי בדיקה ואחד מהבדיקות נכשל. מפעילים רק את הבדיקה שנכשלה 10 פעמים (ברירת המחדל) או עד שהבדיקה עוברת. 
    atest test-to-run --retry-any-failure
  • מפסיקים את ההרצה של הבדיקה שנכשלה אחרי שהיא עוברת או מגיעה לסיבוב ה-100. 
    atest test-to-run --retry-any-failure 100

הרצת בדיקות במכשירי AVD

התכונה Atest יכולה להריץ בדיקות של AVD חדש שנוצר. מריצים את acloud create כדי ליצור מכשיר AVD ולפתח ארטיפקטים, ואז משתמשים בדוגמאות הבאות כדי להריץ את הבדיקות.

הפעלת AVD והרצת בדיקות שלו:

acloud create --local-instance --local-image && atest test-to-run

הפעלת AVD כחלק מהרצת בדיקה:

atest test-to-run --acloud-create "--local-instance --local-image"

מידע נוסף זמין בהרצה של acloud create --help.

העברת אפשרויות למודול

אפשר להעביר אפשרויות למודולים לבדיקה באמצעות Atest. כדי להוסיף אפשרויות לשורת הפקודה של TradeFed להרצת הבדיקה, צריך להשתמש במבנה הבא ולוודא שהארגומנטים המותאמים אישית תואמים לפורמט האפשרות של שורת הפקודה Tradeified.

atest test-to-run -- [CUSTOM_ARGS]

מעבירים את האפשרויות של מודול הבדיקה לגורמים שמכינים את הבדיקה או מפעילים את הבדיקה, שמוגדרים בקובץ התצורה של הבדיקה:

atest test-to-run -- --module-arg module-name:option-name:option-value
atest GtsPermissionTestCases -- --module-arg GtsPermissionTestCases:ignore-business-logic-failure:true

העברת אפשרויות לסוג ריצה או לכיתה:

atest test-to-run -- --test-arg test-class:option-name:option-value
atest CtsVideoTestCases -- --test-arg com.android.tradefed.testtype.JarHosttest:collect-tests-only:true

מידע נוסף על אפשרויות לבדיקה בלבד זמין במאמר העברת אפשרויות למודולים.