從指令列進行測試

本文說明如何直接從指令列執行測試。這份文件假設您已瞭解如何建立 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'

敬上

使用 ADB 執行測試

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

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

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

如何使用 am instrument 進行測試：

建構或重新建構主要應用程式和測試套件。
在目前的 Android 裝置或模擬器上，安裝測試套件和主要應用程式 Android 套件檔案 (APK 檔案)。
在指令列中輸入：
```
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`	`<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 參考資料中查看更多用途。