ffx test run 指令可以在 Fuchsia 裝置上執行測試，並收集測試結果和診斷資訊。
概念
ffx test run 指令會執行與 Fuchsia 測試執行器架構整合的測試，讓您在 Fuchsia 元件中定義及實作測試案例。
如要在 Fuchsia 裝置上執行測試元件，請完成下列步驟：
- 將程式碼、元件和套件定義編譯成 Fuchsia 套件。
- 將套件提供給目標裝置。
- 在目標裝置上執行測試元件。
ffx test 指令只會處理步驟 3。步驟 1 和 2 本質上需要建構系統的相關知識，而 ffx test 則是明確設計為不依賴建構系統。
圖 1. 這個流程圖顯示 ffx test 如何與其他用於編譯和執行測試的工具搭配運作。
ffx test 指令是用來當做由其他工具叫用的較低階工具，通常可以執行特定建構系統或開發環境的測試。本頁記錄的工作流程主要適用於正在努力開發這類高階工具的開發人員。身為測試作者，如果您正在尋找如何在特定專案中執行測試的操作說明，請嘗試檢查專案存放區中的說明文件。如要在 Fuchsia 來源檢出的範圍內執行測試 (fuchsia.git)，請參閱 fx test 說明文件。
不過，在極少數情況下，您可能需要直接叫用 ffx test，才能使用高階工具無法提供的精細選項。此外，專案可能需要支援 ffx test 不支援的其他類型測試，例如主機測試。高階測試指令碼可以直接處理這些問題，或將責任委派給其他工具。舉例來說，fx test 會用來在 Fuchsia SDK 中的 fuchsia.git 和 bazel test 中開發。
執行測試元件
如要在目標裝置上執行測試元件，請執行下列指令：
ffx test run TEST_COMPONENT_URL
將 TEST_COMPONENT_URL 替換為目標測試元件網址。
下列範例指令會在目標裝置上執行 example.cm 元件的測試：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm
使用篩選器執行特定測試案例
如要在測試元件中選擇性地執行測試案例，請執行下列指令：
ffx test run TEST_COMPONENT_URL --test-filter FILTERS
請更改下列內容：
- TEST_COMPONENT_URL – 目標測試元件網址。
- FILTERS - 比對測試案例的模式。
--test-filter 選項中提供的篩選器會根據 glob 模式進行比對。系統只會執行至少符合一個模式的測試案例。舉例來說，假設某個套件包含測試案例 Foo.Test1、Foo.Test2、Bar.Test1 和 Bar.Test2，則下列指令只會執行 Foo.Test1 和 Foo.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter Foo.*
如要指定排除篩選器，請在前方加上 -。如有指定排除篩選器，則系統會排除符合排除篩選器的測試案例。舉例來說，如果使用與上述套件相同的套件，以下指令只會執行 Bar.Test1 和 Bar.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter -Foo.*
您可以多次指定 --test-filter 選項。多個篩選器的行為如下：
- 如未指定篩選器，系統會執行所有測試案例。
- 如果只指定正面篩選條件，系統會執行至少符合一個篩選條件的測試案例。
- 如果只指定排除篩選條件，系統就不會執行任何篩選條件都不符合的測試案例。
- 同時指定正面和負面篩選條件時，系統會執行至少符合一個正面篩選條件，但不符合任何負面篩選條件的測試案例。
使用與上述相同的套件，下列範例指令只會執行 Foo.Test2：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --test-filter Foo.* --test-filter -*.Test1
使用引數執行測試
如要將引數傳遞至測試元件的測試，請執行下列指令：
ffx test run TEST_COMPONENT_URL -- ARGS
請更改下列內容：
- TEST_COMPONENT_URL – 目標測試元件網址。
- ARGS：要傳遞至測試的引數。
以下範例指令會將引數 hello 和 1234 直接傳遞至測試：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm -- hello 1234
執行測試並儲存結構化結果
ffx test run 支援以機器可讀取的格式列印及儲存測試結果，這種格式適合其他工具使用 (如需結構定義的詳細資料，請參閱測試輸出格式)。
如要在執行測試後儲存結構化測試結果，請執行下列指令：
ffx test run TEST_COMPONENT_URL --output-directory DIR
更改下列內容：
- TEST_COMPONENT_URL – 目標測試元件網址。
- DIR：用於儲存結構化測試結果的目錄。
下列範例指令會將輸出內容儲存在 /tmp/ffx-out 目錄中：
$ ffx test run fuchsia-pkg://fuchsia.com/example#example.cm --output-directory /tmp/ffx-out
附錄
傳回碼
ffx test run 在測試順利執行時會傳回零，在失敗時則傳回非零值。ffx test run 支援多個特殊錯誤代碼：
| 名稱 | 結束代碼 | 說明 |
|---|---|---|
| 設定失敗 | 28 | 無法在目標裝置上連線至必要通訊協定 |
| 逾時 | 21 | 因逾時而執行測試失敗 |
中斷信號
傳遞 SIGINT 時 (通常會在終端機中按下 Ctrl+C 來完成)，ffx test run 會嘗試停止進行中的測試並儲存結果。
實驗功能
ffx test run 支援多項實驗功能。這些功能可能會發生重大變更或遭到移除。如要使用實驗功能，您必須選擇加入，方法是將對應的 ffx config 欄位設為 true。如要瞭解可用的實驗功能及啟用方式，請參閱 ffx test run --help。