ffx test run 指令可以在 Fuchsia 裝置上執行測試，並收集測試結果和診斷資訊。
概念
ffx test run 指令會執行與 Fuchsia 測試執行器架構整合的測試，以便在 Fuchsia 元件中定義及實作測試案例。
在 Fuchsia 裝置上執行測試元件需要下列步驟：
- 將程式碼、元件和套件定義編譯至 Fuchsia 套件。
- 向目標裝置提供套件。
- 在目標裝置上執行測試元件。
ffx test 指令只會處理步驟 3。步驟 1 和 2 本身需要瞭解建構系統，且 ffx test 的設計目的在於適用於各種建構系統。
圖 1：此流程圖顯示 ffx test 如何配合編譯與執行測試的其他工具。
ffx test 指令旨在做為較低層級工具，可由其他工具叫用，經常執行建構系統或開發環境專屬的測試。本頁所述的工作流程主要適用於處理這類高階工具的開發人員。如果您是測試作者，而瞭解如何在特定專案中執行測試，請試著檢查專案存放區的說明文件。如要在 Fuuchsia 來源結帳 (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。