本頁面提供最佳做法、範例和參考資料，說明如何使用 fx test 指令在 Fuchsia 來源簽出設定 (fuchsia.git) 中執行測試。
基本用法
如要開始使用，只要執行 fx test 即可：
fx test這會執行下列幾項操作：
- 找出目前版本中包含的測試。
- 根據選取條件選取部分測試項目。
- 重新建構並重新發布這些測試。
- 確認有適當的 Fuchsia 裝置可供執行測試。
- 同時，開始在該裝置上執行測試，並提供狀態輸出。
- 寫入記錄檔，說明發生的作業。
如果建構作業未包含任何測試，fx test 會結束。
在 fx set 指令列上嘗試 fx set core.x64--with //src/diagnostics:tests，加入一些測試做為範例。
如要進一步瞭解 fx test 的目前狀態，請參閱README頁面。
基本概念
fx test 是「測試執行器」，也就是會接收可用測試清單，並負責排定及觀察測試執行情況。這項資料的來源是
tests.json。
tests.json 中列出的每項測試都是「測試套件」，其中可能包含任意數量的「測試案例」。也就是說，測試套件是單一二進位檔或 Fuchsia 元件，其中包含以各測試架構專屬方式定義的測試案例 (例如 C++ TEST、Rust #[test]、Python unittest.TestCase)。列舉及執行裝置端測試案例是測試執行器架構的責任。
選取基本測試
fx test 支援使用指令列選項選取個別測試套件。這樣一來，您就能在建構作業中納入大量測試，然後只執行其中一部分。
傳遞至 fx test 的任何非旗標引數都是選取項目，會與輸入內容中的每個測試進行模糊比對：
fx test archivist --dry根據預設，系統會搜尋下列欄位：
| 欄位 | 說明 |
|---|---|
| name | 測試的完整名稱。這是裝置端測試的元件網址，以及主機測試的測試二進位路徑。 |
| 標籤 | 測試的建構版本標籤。例如：//src/examples:my_test。 |
| 元件名稱 | 元件資訊清單名稱 (不含 .cm)，僅適用於裝置端測試。 |
| 套件名稱 | 僅適用於裝置端測試的 Fuchsia 套件名稱。 |
如要選取來源樹狀結構中某個目錄下方的所有測試，請列出前置字元：
fx test //src/diagnostics/tests --dry系統預設會比對上述所有欄位，但您可以使用 --package 或 --component 選取特定欄位：
fx test --package archivist_unittests --dry根據預設，指令列上的多重選取會實作包含 OR 運算。測試選取作業支援複合式 AND 運算，如下所示：
fx test --package archivist --and unittests --dry這個指令會選取套件符合 archivist 的所有測試，以及符合 unittests 的任何欄位。
如果您知道要執行的測試確切名稱，可以使用 --exact 旗標只選取該測試：
fx test --exact fuchsia-pkg://fuchsia.com/archivist-tests#meta/archivist-unittests.cm --dry如果沒有任何測試符合所選項目，fx test 會嘗試在來源結帳中以啟發式方式比對測試，並建議 fx set 引數來納入這些測試：
$ fx test driver-tests --dry
...
For `driver-tests`, did you mean any of the following?
driver_tools_tests (91.67% similar)
--with //src/devices/bin/driver_tools:driver_tools_tests
driver-runner-tests (90.96% similar)
--with //src/devices/bin/driver_manager:driver-runner-tests
driver-inspect-test (90.96% similar)
--with //src/devices/tests/driver-inspect-test:driver-inspect-test
然後將必要套件新增至建構作業。
基本測試輸出內容
fx test 會將輸出內容儲存在記錄檔中，供日後分析。您可以使用 -pr/--previous 引數，以文字形式查看這份記錄檔的摘要。舉例來說，如要查看先前執行的測試記錄：
$ fx test -pr log
previous-log-file.json.gz:
4 tests were run
[START first_test]
...
[END first_test]
如要查看處理先前記錄檔的完整選項清單，請執行 fx test -pr help。
根據預設，這個指令會處理儲存在 Fuchsia 輸出目錄中的最新記錄，但您可以傳遞 --logpath 來選擇特定記錄。
這個指令可處理毀損或不完整的記錄檔，因此即使您終止執行測試的 fx test 指令，這個指令仍可運作。
基本測試偵錯
fx test 會與 zxdb 整合，提供簡單易用的方式來偵錯測試失敗情形，完全不必重新編譯任何內容。將 --break-on-failure 傳遞至 fx test 呼叫，即可在測試失敗時自動中斷至偵錯工具：
$ fx test --break-on-failure rust_crasher_test.cm
...
⚠️ zxdb caught test failure in rust_crasher_test.cm, type `frame` to get started.
14 LLVM_LIBC_FUNCTION(void, abort, ()) {
15 for (;;) {
▶ 16 CRASH_WITH_UNIQUE_BACKTRACE();
17 _zx_process_exit(ZX_TASK_RETCODE_EXCEPTION_KILL);
18 }
══════════════════════════
Invalid opcode exception
══════════════════════════
Process 1 (koid=107752) thread 1 (koid=107754)
Faulting instruction: 0x4159210ab797
🛑 process 1 __llvm_libc::__abort_impl__() • abort.cc:16
[zxdb] // Now you can debug why the test failed!
您也可以使用 --breakpoint=<location> 選項，在程式碼中的任何位置設定中斷點。<location> 採用標準 zxdb 中斷點語法，通常是檔案和行號或函式名稱：
--breakpoint=my_file.rs:123會在 my_file.rs 的第 123 行設定中斷點。--breakpoint=some_function會在some_function上設定中斷點。
請注意，這個選項會導致測試執行速度大幅變慢，因為 zxdb 需要載入測試的所有符號，才能安裝中斷點。強烈建議您只在 --test-filter 之外使用這個選項。
完成測試失敗的偵錯作業後，您可以輸入 quit、ctrl+d 或 detach *，繼續執行測試。請注意，如果有多個測試案例失敗，系統不會暫停，讓您一併偵錯這些測試。如要瞭解如何偵錯平行發生的多項測試失敗，請參閱偵錯測試。
設定選項
fx test 的可設定程度很高，如需完整的選項清單，請前往 fx test --help。
本節說明如何指定設定選項，以及這些選項的意義。設定選項分為「公用程式」、「建構」、「測試選取」、「執行」或「輸出選項」。這些參數可在指令列或設定檔中指定。
設定檔
fx test 的所有引數都會在指令列上設定，但預設值可能會依使用者設定。如果您在 HOME 目錄中放置名為 .fxtestrc 的檔案，該檔案中的引數就會成為日後 fx test 叫用的新預設值。
例如：
# ~/.fxtestrc
# Lines starting with "#" are comments and ignored.
# The below config roughly matches the behavior of the old Dart-based `fx test`.
# Default parallel to 1.
--parallel 1
# Disable status output.
--no-status
# Print output for tests taking longer than 2 seconds.
--slow 2
上述檔案會覆寫 --parallel 和 --status 旗標的預設值，這些旗標通常分別預設為 4 和 false。叫用 fx test 時，您仍可在指令列覆寫新的預設值。
公用事業選項
公用程式選項會改變 fx test 的整體行為。
--dry執行「試營運」。fx test 會完成測試選取作業，但隨後只會列印所選測試套件的清單，不會執行任何測試。
--list 會以「清單模式」執行 fx test。這個指令不會執行測試，而是列出每個測試套件中的所有測試案例。並輸出適當的指令列，以執行每個個別案例。請注意，您必須存取 Fuchsia 裝置或模擬器，因為測試管理工具會在裝置上列舉測試案例。
-pr/--prev/--previous COMMAND 會處理先前執行 fx test 時的記錄檔，並根據 COMMAND 的值列印資訊。不會執行任何新測試。
這個指令會遵守 --logpath，指定要讀取的記錄檔。
已導入下列 COMMAND：
log會列印記錄檔中記錄的每項測試的指令列和輸出內容。path會列印最近記錄檔的路徑。replay會使用新的顯示選項，重新執行上一次的執行作業。 您可以使用 --replay-speed 引數控制重播速度。值 > 1 可加快輸出速度，值 < 1 則會以慢動作顯示跑步過程。help會列印可用指令的摘要。
建構選項
fx test 預設會建構及更新所選測試。執行 fx -i test 時，這項功能會偵測來源目錄的變更，並在每次修改檔案後重新叫用 fx test，因此非常實用。測試重建作業的運作方式如下 (覆寫設定會列在同一行)。
- 系統會呼叫每個
fx test叫用項目，重建所有選取的測試。fx build <targets>- 使用
--[no-]build鍵切換此行為。
- 使用
- 如果所選測試位於建構的指定套件中 (使用
fx set --with-test指定)，系統會建構updates套件並執行 OTA。- 使用
--[no-]updateifinbase鍵切換此行為。 - 警告：如果目標是模擬器，OTA 會失敗。
- 使用
測試選取選項
下列選項會影響 fx test 選取的測試，以及套用選取內容的方式。
--host 和 --device 分別選取主機或裝置測試。這是通用設定，無法合併使用。
--[no-]e2e 控制是否執行端對端 (E2E) 測試。
根據預設，系統不會執行 E2E 測試，因為這類測試可能會導致裝置處於無效狀態。--only-e2e 會隱含 --e2e，並確保只選取 E2E 測試。
--package (-p) 和 --component (-c) 分別在套件或元件名稱中選取。名稱前面既未選取任何測試欄位。
如要變更多個選取項目，請按一下 --and (-a)。例如：
fx test --package foo -a --component bar //src/other --and --package my-tests上述指令列包含兩個選取子句：
- 套件「foo」和元件「bar」(例如 fuchsia-pkg://fuchsia.com/foo#meta/bar.cm)。
- Package "my-tests" AND //src/other.
系統會選取符合上述任一子句的測試。
系統預設會使用 Damerau-Levenshtein 距離 3，對測試選項進行模糊比對 (例如「my_tset」會比對到「my-test」)。--fuzzy <N> 可用來將這個值覆寫為 N，其中 0 代表不要進行模糊比對。
如果沒有任何測試符合選取子句，系統預設會顯示建議。您可以使用 --suggestions-count N 覆寫建議數量 (預設為 6)，並使用 --[no-]show-suggestions 停用或啟用建議。
執行作業選項
測試會以特定方式執行，盡量提高處理量和穩定性，但您可以覆寫這個預設值的每個元素。測試執行方式如下 (覆寫項目會內嵌列出)：
- 系統會按照所選測試在
tests.json中的顯示順序執行測試。- 使用
--random隨機安排執行順序。
- 使用
- 系統會從上方排序清單的開頭開始，執行所有選取的測試。
- 使用
--offset N略過清單開頭的N測試。預設值為 0。 - 使用
--limit N從偏移值最多執行N項測試。預設為無限制。
- 使用
- 最多可平行執行 4 項測試，其中最多一項測試為「非密封式」(由
test-list.json判斷)。- 如要變更這項預設值，請使用
--parallel N。--parallel 1表示依序執行各項測試。
- 如要變更這項預設值，請使用
- 測試會持續執行，直到自行終止。
- 使用
--timeout N為每項測試設定最多N秒的等待時間。
- 使用
- 每項測試只會執行一次。
- 使用
--count N執行每項測試N次。
- 使用
- 每個測試都會執行所有測試案例。
- 使用
--test-filter僅執行特定名稱的測試案例。
- 使用
- 系統會記錄失敗的測試，並繼續執行下一個選取的測試。
- 使用
--fail(-f) 在第一次失敗後終止所有測試。
- 使用
- 如果測試在
tests.json中指定記錄層級上限，但發現嚴重性較高的記錄，測試就會失敗。- 使用
--[no-]restrict-logs鍵切換此行為。
- 使用
- 測試元件本身會選擇要發出的最低記錄嚴重性。
- 使用
--min-severity-logs覆寫所有測試元件的最低值。
- 使用
- 測試元件會使用建構構件中的 Merkle 根雜湊執行，確保最新建構版本已成功推送至目標並正在執行。
- 使用
--[no-]use-package-hash鍵切換此行為。
- 使用
- 系統不會執行已停用的測試案例。
- 使用
--also-run-disabled-tests仍可執行已停用的測試案例。
- 使用
- 測試輸出記錄只會包含元件路徑名稱的最後一段，因此更容易進行目視檢查。
- 使用
--[no-]show-full-moniker-in-logs鍵切換此行為。
- 使用
測試失敗後會立即終止，不會等待
- 使用
--break-on-failure搭配 zxdb 找出失敗的測試。 - 使用
--breakpoint=<location>在特定 [位置][#basic-test-debugging]安裝中斷點。
請注意，使用
--breakpoint選項會大幅減緩測試速度。強烈建議您只搭配--test-filter使用這個選項。--break-on-failure可用於多項測試，對效能的影響極小。- 使用
測試的指令列引數完全由測試執行工具控管
- 在引數中附加
--，將其餘引數逐字傳遞至測試。舉例來說：fx test foo -- --argument_for_test會將--argument_for_test傳遞至測試本身。
- 在引數中附加
主機測試會自動從使用者環境繼承一組有限的環境變數
- 使用
--env(-e) 為測試新增KEY=VALUE環境變數。這個旗標可多次指定。
- 使用
如果沒有執行任何套件伺服器，系統會在
fx test執行期間啟動臨時伺服器- 使用
--no-allow-temporary-package-server停用這項行為。 - 如果找到現有套件伺服器，系統就不會啟動臨時伺服器。
- 使用
輸出選項
fx test 適用於開發人員用途，內含簡單的終端機 UI，可顯示測試執行狀態。預設輸出行為如下 (覆寫內容會列於同一行)：
- 終端機底部會顯示狀態，並自動更新，顯示目前執行的作業。
- 使用
--[no-]status切換狀態顯示。 - 使用
--status-lines N變更狀態輸出行的數量。 - 使用
--status-delay N變更重新整理頻率 (預設為 0.033 或約 30 Hz)。如果終端機速度緩慢，建議將此值變更為 0.5 或 1。
- 使用
- 輸出內容會以 ANSI 終端機顏色設定樣式。
- 使用
--[no-]style鍵切換此行為。 - 使用
--simple做為--no-style --no-status的簡寫。
- 使用
- 測試輸出內容只會顯示失敗的測試。
- 使用
--output(-o) 顯示所有測試輸出內容 (與--parallel 1搭配使用可避免交錯)。 - 使用
--no-output即可明確隱藏輸出內容，例如覆寫設定中設定的--output。 - 使用
--slow N(-s N) 僅顯示執行時間超過N秒的測試套件輸出內容。
- 使用
- 記錄檔會寫入
fx status指定的建構目錄下，以時間戳記命名的.json.gz檔案。- 使用
--[no-]log即可完全切換記錄功能。 - 使用
--logpath變更記錄檔的輸出路徑。
- 使用
- 測試構件不會從裝置串流傳輸。
- 使用
--artifact-output-directory(--outdir) 指定目錄，構件可能會以ffx test輸出格式串流至該目錄。
- 使用
- 已禁止偵錯列印。
- 使用
--verbose(-v) 將偵錯資訊列印到控制台。 這項資料非常詳細，僅適用於偵錯fx test本身。
- 使用
記錄格式
fx test 的設計宗旨是支援外部工具，方法是將每個使用者可見的輸出內容表示為「事件」，並在執行期間記錄至檔案。
記錄檔會使用 gzip 壓縮。解壓縮後的檔案每行都是一個 JSON 物件，代表一個事件。目前事件結構定義於這個 Python 檔案。
格式穩定後，即可建構互動式檢視器，並轉換為其他格式 (例如建構事件通訊協定)。
常見問題
fx test 無法搭配 Emacs 使用
emacs 編譯視窗不會模擬與 xterm 相容的終端機，因此會導致類似下列的錯誤：
in _make_progress_bar raise ValueError("Width must be at least 3")
如要解決這個問題，請執行 fx test 並使用 --no-status 選項停用狀態列。
fx 測試輸出內容中出現逸出序列
終端機可能不支援 ANSI 顏色代碼，而 fx test 無法偵測到。
將 --no-style 選項傳遞至 fx test，即可停用顏色輸出；將 --no-status 選項傳遞至 fx test，即可停用更新狀態列。將 --simple 選項傳遞至 fx test，等同於 --no-style --no-status。
我不知道記錄檔在哪裡
您可以將 --logpath 傳遞至 fx test 來設定記錄檔的位置，但建議僅在非互動式用途中使用。
根據預設，記錄檔會以加上時間戳記的檔案形式，儲存在 Fuchsia 輸出目錄中。使用 fx test -pr path 列印先前記錄的路徑。
列印記錄檔會將垃圾資料匯入終端機
fx test 記錄檔預設會經過 gzip 壓縮。使用下列指令，將最新記錄以美觀格式輸出至終端機：
cat `fx test -pr path` | gunzip | jq -C | less -R
這項指令會執行以下作業：
- 找出最新的記錄路徑 (
fx test -pr path)。 - 將記錄管道傳送至
gunzip，即可解壓縮記錄。 - 將解壓縮的記錄檔透過管道傳送至
jq，以彩色輸出格式美化列印 (-C)。 - 將顏色輸出內容管道傳輸至設定為顯示顏色 (
-R) 的less。
為方便操作，您可以在 .bashrc 檔案中為這項指令新增別名：
alias testlog='cat `fx test -pr path` | gunzip | jq -C | less -R'
選擇不使用新的 fx 測試指令
新的 fx test 指令目前設為預設指令。
如要停用這項設定，請設定下列環境變數：
export FUCHSIA_DISABLED_legacy_fxtest=0