從指令列進行測試

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

使用 Gradle 建構系統打造應用程式時,Android Gradle 外掛程式可讓您透過指令列在 Gradle 專案中執行測試。如需更多詳細的控管選項,也可以選擇透過 Android Debug Bridge (ADB) 殼層執行測試。

使用 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

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

對模組執行測試

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

./gradlew mylibrary:connectedAndroidTest

對建構變數執行測試

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

  • 本機單元測試:
    ./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 工作叫用 testconnectedAndroidTest 工作,例如:

    ./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.foo/androidx.test.runner.AndroidJUnitRunner
    

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

am 檢測標記

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

表 2. 重要 am 檢測標記

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

am 檢測選項

am 檢測工具會將測試選項以鍵/值組合的形式傳送至 AndroidJUnitRunnerInstrumentationTestRunner,並使用 -e 標記,語法如下:

-e <key> <value>

部分鍵接受多個值,請使用逗號分隔清單指定多個值。舉例來說,當您叫用 AndroidJUnitRunner 時,系統會針對 package 鍵提供多個值:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/android.support.test.runner.AndroidJUnitRunner

下表列出可與測試執行工具搭配使用的鍵/值組合。

表 3. 與測試執行工具搭配使用的 -e 標記鍵/值組合。

說明
package <Java_package_name> 測試應用程式中其中一個套件的完整 Java 套件名稱。系統會執行使用這個套件名稱的所有測試案例類別。請注意,這裡指的不是 Android 套件名稱;測試套件有單一 Android 套件名稱,但其中可能包含多個 Java 套件。
class <class_name> 其中一個測試案例類別的完整 Java 類別名稱。系統只會執行這個測試案例類別。
<class_name>#方法名稱 完整測試案例類別名稱及其中一種方法。系統只會執行這個方法。請特別留意類別名稱和方法名稱之間的雜湊標記 (#)。
func true 執行延伸 InstrumentationTestCase 的所有測試類別。
unit true 執行「不」延伸 InstrumentationTestCasePerformanceTestCase 的所有測試類別。
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
  • 兩種檢測設備測試類別:
    • Foo1,包含 bar1 測試方法,以及
    • Foo2,包含 bar2bar3 測試方法
  • 測試執行工具為 AndroidJUnitRunner

執行完整測試套件

如要執行測試套件中的所有測試類別,請輸入以下內容:

adb shell am instrument -w com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

執行測試案例類別中的所有測試項目

如要執行 Foo1 類別中的所有測試項目,請輸入以下內容:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.Foo1 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

選取部分測試項目

如要執行 Foo1 類別中的所有測試項目以及 Foo2 中的 bar3 方法,請輸入以下內容:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.Foo1,com.android.demo.app.tests.Foo2#bar3 \
> com.android.demo.app.tests/android.support.test.runner.AndroidJUnitRunner

您可以在 AndroidJUnitRunner API 參考資料中查看更多用途。