Fx 測試使用手冊

本頁提供最佳做法、範例和參考資料 使用 fx test 指令在 Fuchsia 來源結帳設定 (fuchsia.git)。

基本用法

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

fx test

這麼做會執行以下動作：

1. 辨識目前版本包含的測試。
2. 根據選取條件挑選要包含的測試子集。
3. 重新建構並重新發布測試。
4. 檢查是否已有適當的 Fuchsia 裝置用於執行測試。
5. 同時，開始在該裝置上執行測試並提供狀態輸出內容。
6. 寫入記錄檔，說明已發生的作業。

如果您未在版本中加入任何測試，fx test 就會結束。 在你的平台上試用 fx set core.x64--with //src/diagnostics:tests fx set 指令列，其中含有一些測試做為範例。

如要進一步瞭解「fx test」目前的狀態，請參閱 README 頁面。

基本概念

fx test 是 Test Executor，表示其會擷取 並負責排程和觀察可用的測試 的執行。這個資料來源 tests.json。

tests.json 中列出的每項測試都是一個測試套件，每個測試都具有 內含任意數量的測試案例。也就是說，測試套件 單一二進位檔或 Fuchsia 元件，而且會包含測試案例 按照每個測試架構 (例如 C++ TEST、Rust #[test]、Python unittest.TestCase)。列舉 並在裝置端執行測試案例負責 測試執行工具 架構。

基本測試選項

fx test 支援使用指令選取個別 TestPackage 線條選項這種做法可讓你進行大量測試 並僅執行一部分測試。

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 會針對系統記錄的每項測試輸出指令列和輸出內容 。
• help 會顯示可用指令的摘要。

建構選項

根據預設，fx test 會建構及更新所選測試。這是 執行 fx -i test 可偵測 來源目錄，並在每個檔案之後重新叫用 fx test 修改內容。測試重新建構作業的運作原理如下 (內嵌覆寫項目會列出)。

• 呼叫 fx build <targets> 即可重新建構所有選取的測試 每次 fx test 叫用。
  • 使用 --[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」套件「和」元件「長條」(例如 fuchsia-pkg://fuchsia.com/foo#meta/bar.cm)。
2. 「my-tests」套件AND //src/other。

選取符合上述任一子句的測試。

使用 Damerau-Levenshtein 測試所選測試選項是否模糊不清 預設距離 3 (例如「my_tset」會對應至「my-test」)。 --fuzzy <N> 可用於將這個值覆寫為 N，其中 0 代表不進行模糊比對。

根據預設，如果沒有測試符合選取條件，系統將顯示建議 子句。可使用以下選項覆寫建議數量 (預設為 6 個)： --suggestions-count N，以及使用以下功能可停用或啟用建議功能： --[no-]show-suggestions。

執行作業選項

測試會以特定方式執行，將處理量最大化，並 但可覆寫這項預設的每個元素。測試 會以下列方式執行 (其中有內嵌覆寫)：

• 系統會按照在 tests.json 內出現的順序執行每項所選測試
  • 使用 --random 隨機將這個執行順序。
• 系統會從上述排序清單的開頭執行所有選定的測試。
  • 使用 --offset N 即可在清單開頭略過 N 測試。預設值為 0。
  • 使用 --limit N 即可從偏移量執行最多 N 個測試。預設值為無限制。
• 同時進行最多 4 項測試，因此最多只能同時執行 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> 在特定位置安裝中斷點 [locations][#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 變更記錄的輸出路徑。
• 測試成果不會從裝置串流出來。
  • 使用 --artifact-output-directory (--outdir) 指定以下位置的目錄： 成果可能會以 ffx test 輸出格式串流。
• 禁止列印偵錯。
  • 使用 --verbose (-v) 將偵錯資訊輸出至控制台。 這項資料極為詳細，僅適用於對 fx test 本身偵錯。

記錄格式

fx test 旨在支援外部工具，因為其代表的是 以「事件」形式向使用者顯示的輸出內容系統會在執行期間記錄檔案

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

等到格式穩定後，您就能製作互動式廣告 以及將訪客轉換為其他格式 (例如建立活動) Protocol (通訊協定))。

常見問題

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 選項，用於停用更新狀態列。傳送 --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) 的美化排版。
• 將顏色輸出傳送至 less，並將其設為顯示顏色 (-R)。

為方便起見，您可以在 .bashrc 檔案中為這個指令新增別名：

alias testlog='cat `fx test -pr path` | gunzip | jq -C | less -R'

停用新的 fx 測試指令

新的 fx test 指令目前設為預設值。

如要停用這項設定，請設定下列環境變數：

export FUCHSIA_DISABLED_legacy_fxtest=0