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