從指令列進行測試

本文說明如何直接從指令列執行測試。這份文件假設您已瞭解如何建立 Android 應用程式以及為應用程式編寫測試程式碼。如要進一步瞭解如何為應用程式建構測試作業，請參閱「在 Android 上測試應用程式」。

使用 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/ 目錄。

檢測設備單元測試 執行 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

您也可以選擇執行 check 和 connectedCheck 的 Gradle 工作。這些工作會分別執行本機或檢測設備測試，但會額外納入由其他 Gradle 外掛程式新增的其他檢查項目。

對模組執行測試

test 和 connectedAndroidTest 工作會對專案中的每個模組執行測試。只要在特定模組前面加上test 或在 connectedAndroidTest 工作前面加上模組名稱和半形冒號 (:)，即可執行測試。舉例來說，下方指令只會執行 mylibrary 模組的檢測設備測試。

./gradlew mylibrary:connectedAndroidTest

對建構變數執行測試

test 和 connectedAndroidTest 工作會對專案中的每個建構變數執行測試。您可以使用下列語法指定特定的建構變數。

  • 本機單元測試： 
    ./gradlew testVariantNameUnitTest
  • 檢測設備測試： 
    ./gradlew connectedVariantNameAndroidTest

執行特定測試方法或類別

執行本機單元測試時，Gradle 可讓您使用 --tests 標記指定特定測試項目。舉例來說，以下指令只會為指定建構變數執行 sampleTestMethod 測試。想進一步瞭解如何使用 --tests 標記，請參閱 Gradle 的測試篩選功能說明文件。


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

檢測設備測試的多模組報表

如表 1 所述，Gradle 會將檢測設備測試結果儲存至每個受測模組的 build/ 目錄中。不過，為多個模組執行測試時，建議您將所有測試結果彙整為單一報表。如要在執行多個模組的測試時產生單一報表，請按照下列步驟操作：

  1. 在專案層級的 build.gradle 檔案中，在 buildscript{} 區塊後方新增以下內容：

    Groovy

    apply plugin: 'android-reporting'

    Kotlin

    apply(plugin = "android-reporting")

  2. 透過 mergeAndroidReports 工作叫用 test 或 connectedAndroidTest 工作，例如：

    ./gradlew connectedAndroidTest mergeAndroidReports

    如要略過失敗的測試，以便 Gradle 完成所有剩餘測試，請新增 --continue 選項：

    ./gradlew connectedAndroidTest mergeAndroidReports --continue

當 Gradle 完成執行所有測試後，會將彙整結果儲存在 path_to_your_project/build/ 目錄中。

使用 ADB 執行測試

與其他測試方法相比，使用 Android Debug Bridge (ADB) 透過指令列執行測試時，您可以選擇更多執行測試的設定選項。您可以選取個別測試方式、根據自訂註解篩選測試項目，或者指定測試選項。由於測試執行作業可完全透過指令列控管，因此您可以使用殼層指令碼，以多種方式自訂測試內容。

如要從指令列執行測試，請執行 adb shell 在裝置或模擬器上啟動指令列殼層。您可以在殼層中使用 am 指令與活動管理員互動，並使用其 instrument 子指令執行測試。

如需更為簡便的方法，您可以依序啟動 ADB 殼層、呼叫 am instrument，然後在單一輸入行中指定指令列標記。殼層即會在裝置或模擬器中開啟，並執行測試及產生輸出內容，然後將內容傳回電腦上的指令列。

如何使用 am instrument 進行測試：

  1. 建構或重新建構主要應用程式和測試套件。
  2. 在目前的 Android 裝置或模擬器上，安裝測試套件和主要應用程式 Android 套件檔案 (APK 檔案)。

  3. 在指令列中輸入：

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

    其中 <test_package_name> 是測試應用程式的 Android 套件名稱，而 <runner_class> 是您要使用的 Android 測試執行工具類別名稱。Android 套件名稱指的是測試套件資訊清單檔案 (AndroidManifest.xml) 中資訊清單元素的套件屬性值。

    Android 測試執行工具類別通常是 AndroidJUnitRunner：

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

您的測試結果會顯示在 STDOUT 中。

am 檢測標記

您可以執行 adb shell am help，藉此找出搭配 am instrument 指令使用的所有標記清單。下表將說明部分重要標記：

表 2. 重要 am instrument 標記

標記 值 說明
-w (無) 強制 am instrument 必須等候檢測作業終止後才能終止。這是為了確保殼層在測試完成前都能保持開啟。您需要這個標記才能查看測試結果。
-r (無) 輸出結果會以原始格式產生。如要收集效能評估結果，請使用這個標記，讓系統不要將評估結果轉換為測試結果。這個標記適合與 -e perf true 標記搭配使用 (相關說明請參閱「am 檢測選項」一節)。
-e <test_options> 提供測試選項做為鍵/值組合。am instrument 工具會使用其 onCreate() 方法，將這些值傳送至指定的檢測類別。您可以指定多個 -e <test_options>。如要瞭解鍵和值，請參閱「am 檢測選項」一節的説明。您只能將這些鍵/值組合與 AndroidJUnitRunner 或 InstrumentationTestRunner 及其子類別搭配使用。如果與任何其他類別搭配使用，則不會有任何效果。
--no-hidden-api-checks (無) 停用隱藏 API 的使用限制。如要進一步瞭解隱藏 API 及其對應用程式的影響，請參閱「非 SDK 介面的相關限制」。

am 檢測選項

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 的所有測試類別。 使用這個選項時，請一併指定 am instrument 的 -r 標記，讓系統以原始格式保留輸出內容，而且不會將輸出內容轉換為測試結果的格式。
debug true 以偵錯模式執行測試。
log true 載入並記錄所有指定的測試，但不會進行執行。測試資訊會顯示在 STDOUT 中。您可以使用這個選項來驗證其他篩選器和測試規格的組合。
emma true 執行 EMMA 程式碼涵蓋率分析，並將輸出內容寫入裝置上的 /data/<app_package>/coverage.ec。如要覆寫檔案位置，請使用以下項目列出的 coverageFile 鍵。

注意：如要使用這個選項，您必須透過 coverage 目標建立測試應用程式的 EMMA 檢測版本。

coverageFile <filename> 覆寫裝置上 EMMA 涵蓋率檔案的預設位置。請以 UNIX 格式將這個值指定為路徑和檔案名稱。 您可以在 emma 鍵的項目中查看預設檔案名稱說明。

使用 -e 標記時，請注意下列事項：

  • am instrument 會使用包含鍵/值組合的 Bundle 叫用 onCreate(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 類別中的所有測試項目以及 TestClass2 中的 testMethod3 方法，請輸入以下內容：

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 參考資料中查看更多用途。