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

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

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

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

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

כדי להוסיף תכונה ל-Atest, פועלים לפי תהליך העבודה של מפתחים ב-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] הפעלה מחדש של כל הבדיקות עד שמתרחשת כשל או שמגיעים לחזרה על הבדיקה (iteration) המקסימלית. (10 כברירת מחדל)
--retry-any-failure [COUNT=10] הבדיקה מופעל מחדש עד שהיא עוברת או עד שמגיעים לחזרה על הבדיקה (iteration) המקסימלית. (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

כדי להריץ בדיקות שמשולבות ישירות ב-TradeFed (לא מודולים), מזינים את השם כפי שהוא מופיע בפלט של הפקודה 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

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

משתמשים באפשרויות -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

אפשר להשתמש ב-Atest כדי לאלץ בדיקה לדלג על שלב הניקוי או הניתוק. בדיקות רבות, כמו 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: מריצים רק בדיקות שנכשלו עד שהן עוברות או עד שמגיעים לחזרה (iteration) המקסימלית.

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

הפעלת בדיקות במכשירי AVD

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

מפעילים מכונה וירטואלית ל-Android ומריצים בה בדיקות:

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 להרצת הבדיקה, משתמשים במבנה הבא ומוודאים שהארגומנטים המותאמים אישית עומדים בפורמט של אפשרויות שורת הפקודה של Tradefed.

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

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