ทดสอบจากบรรทัดคำสั่ง

เอกสารนี้อธิบายวิธีเรียกใช้การทดสอบจากบรรทัดคำสั่งโดยตรง เอกสารนี้ถือว่าคุณรู้วิธีสร้างแอป Android และเขียนการทดสอบสำหรับแอปอยู่แล้ว ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีสร้างการทดสอบสำหรับแอปได้ที่ทดสอบแอปใน Android

เครื่องมือบรรทัดคำสั่งและงาน Gradle ที่อธิบายไว้ในหน้านี้ไม่ขึ้นอยู่กับ UI-toolkit หากต้องการเขียนการทดสอบ UI สำหรับ Compose โปรดดู ทดสอบเลย์เอาต์ Compose หลังจากเขียนการทดสอบแล้ว ให้ทำตามคำแนะนำนี้เพื่อเรียกใช้การทดสอบจากเทอร์มินัลหรือสภาพแวดล้อมการผสานรวมอย่างต่อเนื่องระยะไกล

เมื่อสร้างแอปโดยใช้ระบบบิลด์ Gradle ปลั๊กอิน Android Gradle จะช่วยให้คุณเรียกใช้การทดสอบจากโปรเจ็กต์ Gradle โดยใช้บรรทัดคำสั่งได้ หากต้องการควบคุมอย่างละเอียดมากขึ้น คุณสามารถ เลือกที่จะเรียกใช้การทดสอบผ่านเชลล์ Android Debug Bridge (adb) ซึ่งอาจมีประโยชน์เมื่อเรียกใช้การทดสอบในสภาพแวดล้อมการรวมอย่างต่อเนื่อง

ดูวิธีเรียกใช้การทดสอบที่มีการตรวจสอบโดยอัตโนมัติจากบรรทัดคำสั่งโดยใช้อุปกรณ์เสมือนที่ Gradle จัดการให้ได้ที่ขยายขนาดการทดสอบด้วยอุปกรณ์ที่ Gradle จัดการ

เรียกใช้การทดสอบด้วย Gradle

ปลั๊กอิน Android Gradle ช่วยให้คุณเรียกใช้การทดสอบจากโปรเจ็กต์ Gradle ได้โดยใช้ บรรทัดคำสั่ง

ตารางด้านล่างสรุปวิธีเรียกใช้การทดสอบด้วย Gradle

ตารางที่ 1 วิธีต่างๆ ในการเรียกใช้การทดสอบด้วย Gradle

ประเภทการทดสอบหน่วย คำสั่งที่จะเรียกใช้ ตำแหน่งผลการทดสอบ
การทำ Unit Test ในเครื่อง เรียกใช้งาน test ดังนี้ 

./gradlew test
ไฟล์ผลการทดสอบ HTML:
path_to_your_project/module_name/build/reports/tests/

ไฟล์ผลการทดสอบ XML:
path_to_your_project/module_name/build/test-results/ directory

Unit Test ที่มีการตรวจสอบ เรียกใช้งาน 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 รองรับตัวย่อชื่อ Task ตัวอย่างเช่น คุณสามารถเริ่มงาน connectedAndroidTest ได้โดย ป้อนคำสั่งต่อไปนี้

./gradlew cAT

นอกจากนี้ คุณยังเลือกเรียกใช้ Gradle Task check และ connectedCheck ได้ด้วย งานเหล่านี้จะเรียกใช้การทดสอบในเครื่องหรือการทดสอบที่วัดประสิทธิภาพตามลำดับ แต่ รวมถึงการตรวจสอบอื่นๆ ที่เพิ่มโดยปลั๊กอิน Gradle อื่นๆ ด้วย

เรียกใช้การทดสอบในโมดูล

งาน test และ connectedAndroidTest จะเรียกใช้การทดสอบในแต่ละโมดูลในโปรเจ็กต์ คุณสามารถเรียกใช้การทดสอบในโมดูลที่เฉพาะเจาะจงได้โดย นำหน้างาน test หรือ connectedAndroidTest ด้วยชื่อโมดูลและ เครื่องหมายโคลอน (:) เช่น คำสั่งต่อไปนี้จะเรียกใช้การทดสอบที่ใช้เครื่องมือสำหรับโมดูล mylibrary เท่านั้น

./gradlew mylibrary:connectedAndroidTest

เรียกใช้การทดสอบในตัวแปรบิลด์

งาน test และ connectedAndroidTest จะเรียกใช้การทดสอบในตัวแปรบิลด์แต่ละรายการในโปรเจ็กต์ คุณกำหนดเป้าหมายตัวแปรบิลด์ที่เฉพาะเจาะจงได้โดยใช้ไวยากรณ์ต่อไปนี้

  • สำหรับการทดสอบหน่วยในเครื่อง ให้ทำดังนี้ 
    ./gradlew testVariantNameUnitTest
  • สำหรับการทดสอบที่มีการตรวจสอบ 
    ./gradlew connectedVariantNameAndroidTest

เรียกใช้เมธอดหรือคลาสการทดสอบที่เฉพาะเจาะจง

เมื่อเรียกใช้ Unit Test ในเครื่อง Gradle จะช่วยให้คุณกำหนดเป้าหมายการทดสอบที่เฉพาะเจาะจงได้โดยใช้ Flag --tests เช่น คำสั่งต่อไปนี้จะเรียกใช้เฉพาะ sampleTestMethod การทดสอบสำหรับตัวแปรบิลด์ที่ระบุ ดูข้อมูลเพิ่มเติมเกี่ยวกับ การใช้แฟล็ก --tests ได้ในเอกสารประกอบของ Gradle เกี่ยวกับ การกรองการทดสอบ


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

เรียกใช้การทดสอบด้วย adb

เมื่อเรียกใช้การทดสอบจากบรรทัดคำสั่งด้วย Android Debug Bridge (adb) คุณจะมีตัวเลือกเพิ่มเติมสำหรับ การเลือกการทดสอบที่จะเรียกใช้มากกว่าวิธีอื่นๆ คุณสามารถเลือกวิธีการทดสอบแต่ละรายการ กรองการทดสอบตามคำอธิบายประกอบที่กำหนดเอง หรือระบุตัวเลือกการทดสอบ เนื่องจากการทดสอบรันได้รับการควบคุมจากบรรทัดคำสั่งทั้งหมด คุณจึงปรับแต่งการทดสอบด้วยสคริปต์เชลล์ได้หลายวิธี

หากต้องการเรียกใช้การทดสอบจากบรรทัดคำสั่ง ให้เรียกใช้ adb shell เพื่อเริ่มเชลล์บรรทัดคำสั่ง ในอุปกรณ์หรือโปรแกรมจำลอง ภายในเชลล์นั้น คุณสามารถโต้ตอบกับ Activity Manager โดยใช้คำสั่ง am และใช้คำสั่งย่อย instrument เพื่อเรียกใช้การทดสอบ

คุณสามารถเริ่มเชลล์ adb, เรียกใช้ 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 คือค่าของแอตทริบิวต์แพ็กเกจขององค์ประกอบ Manifest ในไฟล์ Manifest ของแพ็กเกจทดสอบ (AndroidManifest.xml)

    โดยปกติแล้ว คลาสโปรแกรมเรียกใช้การทดสอบ Android จะเป็น AndroidJUnitRunner

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

ผลการทดสอบจะปรากฏใน STDOUT

am instrument flags

หากต้องการดูรายการ Flag ทั้งหมดที่จะใช้กับคำสั่ง 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 ชื่อคลาสกรณีทดสอบที่สมบูรณ์และวิธีการอย่างใดอย่างหนึ่งของคลาส เฉพาะ เมธอดนี้เท่านั้นที่จะดำเนินการ โปรดสังเกตเครื่องหมายแฮช (#) ระหว่างชื่อคลาส กับชื่อเมธอด
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
  • คลาสการทดสอบที่มีการตรวจสอบ 2 คลาส
    • 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

ดู Use Case เพิ่มเติมได้ใน AndroidJUnitRunner เอกสารอ้างอิง API

ดูรายงานการทดสอบแบบรวม

ปลั๊กอิน Android Gradle มีงานทดสอบแบบรวม ซึ่งจะสร้างแดชบอร์ด HTML ที่ผสานผลลัพธ์จากการทดสอบหน่วยและการทดสอบที่มีการวัดคุม

สิ่งที่ต้องมีก่อน

  • ปลั๊กอิน Android Gradle 9.5.0-alpha05 ขึ้นไป

หากต้องการทดสอบชุดการทดสอบทั้งหมด ให้เรียกใช้หนึ่งในงานต่อไปนี้

ขอบเขตของรายงาน คำสั่ง คำอธิบาย ตำแหน่งที่รายงาน
โมดูลปัจจุบัน ./gradlew :module_name:testAllSuites สร้างรายงานการทดสอบแบบรวมสำหรับโมดูลปัจจุบัน โดยผสานผลการทดสอบ Unit Test และการทดสอบที่มีการตรวจสอบ path_to_your_project/module_name/build/reports/tests/test-report/
โมดูลปัจจุบันและทรัพยากร Dependency ./gradlew :module_name:testAllSuitesWithDependencies สร้างรายงานการทดสอบแบบรวมสำหรับโมดูลปัจจุบันและการอ้างอิงไลบรารี โดยผสานผลการทดสอบหน่วยและการทดสอบที่มีการวัด path_to_your_project/module_name/build/reports/tests/aggregated-test-report/