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

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

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

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

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

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

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

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

ประเภท Unit Test คำสั่งที่เรียกใช้ ตำแหน่งผลการทดสอบ
Local 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/ ไดเรกทอรี

การทดสอบ 1 หน่วยแบบมีเครื่องควบคุม เรียกใช้งาน 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/ ไดเรกทอรี

Gradle รองรับ การย่อชื่อของงาน. ตัวอย่างเช่น คุณสามารถเริ่มงาน connectedAndroidTest ได้โดยป้อนคำสั่งต่อไปนี้

./gradlew cAT

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

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

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

./gradlew mylibrary:connectedAndroidTest

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

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

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

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

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


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

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

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

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

คุณสามารถเริ่มเชลล์ adb เรียกใช้ am instrument และระบุแฟล็กบรรทัดคำสั่งทั้งหมดในบรรทัดอินพุตเดียวได้ เชลล์จะเปิดขึ้นในอุปกรณ์หรือโปรแกรมจำลอง เรียกใช้การทดสอบ สร้างเอาต์พุต แล้วกลับไปที่บรรทัดคำสั่งในคอมพิวเตอร์

วิธีเรียกใช้การทดสอบด้วย am instrument

  1. สร้าง หรือสร้างใหม่แอปพลิเคชันหลักและ แพ็กเกจทดสอบ
  2. ติดตั้งแพ็กเกจทดสอบและไฟล์แพ็กเกจแอปพลิเคชันหลักของ Android (ไฟล์ APK) ในอุปกรณ์ Android หรือโปรแกรมจำลอง Android ปัจจุบัน

  3. ป้อนคำสั่งต่อไปนี้ในบรรทัดคำสั่ง

    adb shell am instrument -w <test_package_name>/<runner_class>

    โดยที่ <test_package_name> คือชื่อแพ็กเกจ Android ของแอปพลิเคชันทดสอบ และ <runner_class> คือชื่อคลาสตัวเรียกใช้การทดสอบ Android ที่คุณใช้ ชื่อแพ็กเกจ Android คือค่าของแอตทริบิวต์แพ็กเกจขององค์ประกอบ Manifest ในไฟล์ Manifest ของแพ็กเกจทดสอบ (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 instrument)
-e <test_options> ระบุตัวเลือกการทดสอบเป็นคู่คีย์-ค่า เครื่องมือ am instrument จะส่งตัวเลือกเหล่านี้ไปยังคลาสการวัดคุมที่ระบุ โดยใช้เมธอด onCreate() คุณสามารถระบุ -e <test_options> ได้หลายครั้ง คีย์และค่าจะ อธิบายไว้ใน ส่วนตัวเลือก am instrument คุณใช้คู่คีย์-ค่าเหล่านี้ได้กับ AndroidJUnitRunner หรือกับ InstrumentationTestRunner และคลาสย่อยเท่านั้น การใช้กับคลาสอื่นๆ จะไม่มีผล
--no-hidden-api-checks (ไม่มี) ปิดใช้ข้อจำกัดในการใช้ API ที่ซ่อนอยู่ ดูข้อมูลเพิ่มเติมเกี่ยวกับ API ที่ซ่อนอยู่และวิธีที่ API เหล่านี้อาจส่งผลต่อแอปได้ที่ ข้อจำกัดเกี่ยวกับอินเทอร์เฟซที่ไม่ใช่ SDK

ตัวเลือก am instrument

เครื่องมือ 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 ชื่อคลาสกรณีทดสอบที่สมบูรณ์ในตัวเองและเมธอดใดเมธอดหนึ่งของคลาส ระบบจะเรียกใช้เมธอดนี้เท่านั้น โปรดสังเกตเครื่องหมายแฮช (#) ระหว่างชื่อคลาส กับชื่อเมธอด
func true เรียกใช้คลาสการทดสอบทั้งหมดที่ขยาย InstrumentationTestCase
unit true เรียกใช้คลาสการทดสอบทั้งหมดที่ ไม่ ขยาย InstrumentationTestCase หรือ PerformanceTestCase
size [small | medium | large] เรียกใช้เมธอดการทดสอบที่มีคำอธิบายประกอบตามขนาด คำอธิบายประกอบคือ @SmallTest, @MediumTest และ @LargeTest
perf true เรียกใช้คลาสการทดสอบทั้งหมดที่ใช้ PerformanceTestCase เมื่อใช้ตัวเลือกนี้ ให้ระบุแฟล็ก -r สำหรับ am instrument เพื่อให้เอาต์พุตอยู่ในรูปแบบข้อมูลดิบ และไม่จัดรูปแบบใหม่เป็นผลการทดสอบ
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

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

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

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

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

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

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

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