| RFC-0163：測試輸出格式 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 定義 (但尚未使用) ffx 測試產生的初始穩定版測試輸出格式。 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2022-02-22 |
| 審查日期 (年-月-日) | 2022-05-18 |
舊版 API 設計文件
這項 RFC 先前是以 API 設計文件提交，後來在 API 設計文件範本淘汰後轉換為 RFC。
摘要
本文件提出了穩定的輸出格式，可透過透過 Fuchsia SDK 提供的測試工具輸出目錄。
目標和用途
測試架構可讓用戶同時排程及執行多項測試，並為每項測試收集大量診斷構件。ffx test 是主機工具，可讓用戶端與測試架構互動。
叫用 ffx test 的自動化工具 (例如在 CI 基礎架構中執行的工具) 需要一種方法，可在測試執行期間可靠地取得完整的結果和構件集合。目前，這些工具會透過剖析 stdout 取得測試結果，但這項做法不夠穩定，無法呈現 Test Architecture 收集到的完整一組構件。這項設計旨在提供穩定的輸出格式，以便機器進行最佳化剖析。
磁碟上的穩定格式也能讓開發人員在測試執行後檢查結果，或與其他開發人員分享結果。
ffx test 的用途是給 SDK 消費者使用，為確保工具更新不會影響這些使用者的工具，格式必須提供穩定性保證。
此輸出格式並非用來取代測試成功或失敗的所有信號。舉例來說，ffx test 仍會支援人類可讀的輸出內容，以及用於指出成功或失敗的傳回碼。
背景
單一執行 ffx test 會產生測試執行。測試執行程序由套件組成，而每個套件都由測試案例組成。
「套件執行作業」是指執行測試元件。測試元件最常透過網址識別，例如 fuchsia-pkg://fuchsia.com/run_test_suite_integration_tests#meta/passing-test-example.cm。在一次測試執行中，同一個套件可能會執行多次。在這種情況下，會有多個獨立的套件執行作業。
測試案例是指執行套件中包含的單一測試案例。同一個測試案例可能會在套件執行期間多次執行。在這種情況下，會有多個測試案例。
構件是指測試架構收集的診斷輸出內容。構件的範圍為測試執行作業、測試套件執行作業或測試案例。舉例來說，Test Architecture 目前會為每個測試案例收集 stdout 和 stderr，但會為每個測試套件執行作業收集 syslog。
設計
總覽
測試輸出內容會儲存為目錄。目錄的根目錄包含單一 JSON 檔案和任意數量的子目錄。子目錄會包含範圍限定為單一測試案例、測試套件或測試執行作業的構件。JSON 檔案包含測試結果、測試執行作業的詳細資料，並列出目錄中包含的構件。
目錄版面配置
JSON 檔案一律會命名為 run_summary.json，且一律位於目錄的頂層。run_summary.json 包含整體測試執行作業、測試執行作業中的套件執行作業，以及每個套件執行作業中的測試案例的完整結果集。它還包含每個構件子目錄的名稱，以及其中的構件清單。
子目錄和子目錄內的構件名稱未指定。子目錄和構件實際名稱會在 run_summary.json 中定義。構件一律位於構件子目錄的頂層。
JSON 結構定義
JSON 結構定義會放在 //sdk/schema/ffx_test 下方，並透過 SDK 匯出。結構定義演進功能會依賴 RFC-0100 中引進的結構定義版本控制機制。
初始版的結構定義已在這個修訂版本中定義。
工具的使用情形
需要解讀測試結果的工具應先剖析 run_summary.json，這是輸出格式中唯一具有定義位置的檔案。run_summary.json 包含完整的結果集和所有構件參照。工具不應假設輸出內容中的任何其他位置都是穩定的。
未知
輸出格式可能會根據使用者需求進行更新。舉例來說，我們可能會更新格式，以便在我們發現的常見用途中簡化剖析作業。
可用性
擴充性和演進
我們預期的主要擴充功能是新增測試狀態和構件類型。一般來說，結構定義中新增的列舉變數和 JSON 欄位不會造成重大變更，而使用輸出的工具可以安全地忽略不瞭解的欄位和列舉變數。重大變更包括修改必要欄位，以及變更目錄結構。在這些情況下，系統會按照 RFC-0100 中的策略，在 SDK 中產生並發布新版 JSON 結構定義。
類似的輸出內容
除了 Fuchsia 之外，還有許多個別的測試架構，可支援多種機器可讀的測試結果格式。舉例來說，googletest 同時支援 JSON 和 XML 輸出格式。
測試
測試主要會依賴單元和整合測試，確認 ffx test 產生的輸出內容是否符合輸出格式。
效能考量
產生這個檔案格式不應耗費太多時間。原型實作可儲存包含 100,000 個測試案例的套件，每個測試案例都包含 stdout 和 stderr 構件，產生及儲存 run_summary.json 只需不到一秒的時間，其磁碟大小約為 26 MB。假設有 1,000,000 個案例，同一個原型在磁碟上產生 run_summary.json 大約需要 15 秒，大小約為 256 MB。無論如何，原型設計的記憶體用量上限大約是磁碟上摘要的兩倍。
比較來說，Chromium 中的大型已知測試套件包含約 100,000 個案例。由於為這麼多個案例儲存 run_summary.json 只需不到一秒的時間，因此應該不會造成問題。
在 fuchsia.git 中，目前最大的測試套件含有約 300 到 400 個測試案例，而單一基礎架構區塊可能含有約 300 個套件。針對 fuchsia.git，我們打算使用 ffx 測試的多重測試功能，這項功能會將所有測試案例的結果儲存於單一輸出目錄。因此在這個案例中，run_summary.json 最多會包含 120,000 個案例，我們估計這些案例在磁碟上所占空間不到 50 MB，且儲存時間約為 1 秒。
開發人員會重複執行測試，因此有許多常見的本機開發流程。舉例來說，開發人員可能會反覆執行測試，以重現不穩定的失敗情形。在這種情況下，我們可以輕鬆執行數千個測試案例的批次，且記憶體用量不會超過 10 MB。
安全性考量
這項輸出內容只用於儲存測試產生的結果和構件，且已由測試架構提供，不會引入額外的安全性考量。
隱私權注意事項
這項輸出內容只用於儲存測試產生的結果和構件，且已由測試架構提供，不會引入其他隱私權考量。
缺點和替代方案
根據預設，輸出格式支援多個測試套件的執行作業。這會讓只會一次執行一個測試的用戶端難以解析。另一種做法是支援輸出格式，其中包含單一測試套件執行結果，以及包含多個測試套件執行結果的第二種輸出格式。雖然這可簡化即時剖析作業，但有多種格式會使分析輸出的共用工具變得複雜。
另一種做法是使用多個 JSON 檔案來儲存測試結果。使用單一檔案儲存所有測試結果的缺點之一，是與該檔案互動的工具必須一次保留整個內容。從原型中，我們需要約 400 萬個測試案例，run_summary.json 才會超過 1 GB，此時序列化作業大約需要一分鐘。由於目前的使用情境比這還要少上好幾個數量級，因此目前還不需要使用多個檔案。由於在多個檔案中儲存結果會使剖析作業變得複雜，因此我們會使用單一檔案。
第三個替代做法是將所有構件儲存在 run_summary.json 中，進一步簡化剖析作業。這項做法有個缺點，就是構件現在也必須保留在記憶體中。目前收集到的最大成果是用於涵蓋率的設定檔資料。在單一基礎架構分片中，這類設定檔資料約為 500 MB，分散在多個檔案中。雖然這個設定檔不會超過 1 GB，但如果同時變更測試分割方式和設定檔資料的呈現方式，檔案大小可能會迅速接近 1 GB。