本頁面提供最佳做法、範例和參考資料，說明如何使用 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) 專屬方式定義的測試案例。列舉並執行裝置端測試案例是Test Runner 架構的責任。
基本測試選項
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 裝置或模擬器，因為 Test Manager 會在裝置上列舉個案。
-pr/--prev/--previous COMMAND 會處理先前執行 fx test 時產生的記錄檔，並根據 COMMAND 的值列印資訊。不會執行任何新測試。這個指令會遵循 --logpath 指定要讀取的記錄。
實作的 COMMAND 如下：
log會針對記錄在記錄檔中的每個測試，列印指令列和輸出內容。path會列印最近記錄檔的路徑。replay會使用新的顯示選項重播先前的執行作業。您可以使用 --replay-speed 引數控制重播速度。值大於 1 會加快輸出速度，值小於 1 則會以慢動作顯示執行情形。help會列印可用指令的摘要。
建構選項
fx test 預設會建構及更新所選測試。這在執行 fx -i 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，並確保只選取端對端測試。
--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)。
- 套件「my-tests」和 //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 適用於開發人員用途，並包含簡單的終端機 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 檔案中。
格式穩定後，您就可以建立互動式檢視器，並將其轉換為其他格式 (例如 Build 事件通訊協定)。
常見問題
fx 測試無法與 emacs 搭配運作
emacs 編譯視窗不會模擬與 xterm 相容的終端機，導致發生以下錯誤：
in _make_progress_bar raise ValueError("Width must be at least 3")
如要解決這個問題，請使用 --no-status 選項執行 fx test，以便停用狀態列。
在 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 test 指令
新的 fx test 指令目前設為預設值。
如要停用這項設定，請設定下列環境變數：
export FUCHSIA_DISABLED_legacy_fxtest=0