robots: noindex
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。