Fx 測試使用手冊

本頁面提供最佳做法、範例和參考資料，說明如何使用 fx test 指令在 Fuchsia 來源檢查作業設定 (fuchsia.git) 中執行測試。

基本用法

如要開始使用，只要執行 fx test 即可：

fx test

這麼做可以達到以下幾個目的：

1. 找出目前版本中包含的測試。
2. 根據選取條件選取部分納入的測試。
3. 重新建構並重新發布這些測試。
4. 確認是否有適當的 Fuchsia 裝置可用於執行測試。
5. 並行在該裝置上執行測試，並提供狀態輸出內容。
6. 寫入記錄檔案，說明發生的作業。

如果您未在建構中加入任何測試，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

上述指令列包含兩個選取子句：

1. 檔案包「foo」和元件「bar」(例如 fuchsia-pkg://fuchsia.com/foo#meta/bar.cm)。
2. 套件「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