Fx 測試使用手冊

fx test 是開發人員進入點，可在 fuchsia.git 結帳服務中執行測試。

本文件提供開發人員導向的指南，說明如何使用 fx test 進行樹狀結構內測試。

基本用法

如要開始使用，只要執行 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 是一種 Test Executor，表示會擷取可用的測試清單，並負責排程及觀察執行作業。這項資料的來源是 tests.json。

tests.json 中列出的每項測試都是測試套件，每個測試可能包含任意數量的測試案例。也就是說，測試套件是單一二進位檔或 Fuchsia 元件，其中包含以每個測試架構專屬方式定義的測試案例 (例如 C++ TEST、Rust #[test]、Python unittest.TestCase)。列舉及執行裝置端測試案例，由測試執行器架構負責。

選擇基本測試

fx test 支援使用指令列選項選取個別測試套件。這樣就能在建構作業中納入大量測試，然後只執行其中一部分的測試。

fx test 的任何非旗標引數都是選項，與輸入中的每個測試進行比對：

fx test archivist --dry

根據預設，系統會搜尋下列欄位：

廣闊	說明
name	測試的全名。這是裝置端測試的元件網址，以及主機測試的二進位檔路徑。
label	測試的版本標籤。例如：//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 會顯示指令列，並根據記錄檔中記錄的每個測試輸出輸出內容。
• help 會顯示可用指令的摘要。

建構選項

根據預設，fx test 會建構及更新所選的測試。這在執行 fx -i test 時相當實用，能偵測來源目錄的變更，並在每次檔案修改後重新叫用 fx test。測試重新建構的運作方式如下 (內嵌所列覆寫設定)。

• 系統會針對每個 fx test 叫用呼叫 fx build <targets>，藉此重新建構所有選定的測試。
  • 如要切換這個行為，請使用 --[no-]build。
• 如果選取的測試位於建構作業的「基本套件」中 (使用 fx set --with-base 指定)，系統就會建構 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

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

1. 封裝 "foo" AND 元件「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 秒的測試套件顯示輸出內容。
• 記錄檔會寫入已加上時間戳記的 .json.gz 檔案 (位於 fx status 指定的建構目錄下)。
  • 請使用 --[no-]log 完全切換記錄。
  • 使用 --logpath 變更記錄的輸出路徑。
• 測試成果不會從裝置串流到外部。
  • 使用 --ffx-output-directory 指定可能會以 ffx test 輸出格式串流構件的目錄。
• 抑制列印偵錯功能。
  • 使用 --verbose (-v) 在控制台中列印偵錯資訊。這項資料「極度」extremely涵蓋，僅適用於對 fx test 本身偵錯時使用。

記錄格式

fx test 的設計目的是在支援外部工具時，將每位使用者可見的輸出內容指定為「事件」，並在執行期間記錄為檔案。

記錄檔使用 gzip 壓縮檔。解壓縮檔案的每一行都是代表一個事件的單一 JSON 物件。事件結構定義目前在這個 Python 檔案中定義。

如果格式穩定，即可建立互動式檢視器和轉換器，轉換成其他格式 (例如建構事件通訊協定)。