| RFC-0163：測試輸出格式 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 定義 ffx 測試產生的測試輸出格式初始穩定版本，但尚未採用。 |
| 問題 | |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 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。在測試執行中，同一套件可能會多次執行。在這種情況下，會有多次獨立的測試套件執行。
測試案例是指執行套件中包含的單一測試案例。在套件執行中，同一個測試案例可能會多次執行。在本例中，有多個測試案例。
構件是測試架構收集的診斷輸出內容。構件的範圍可以是測試執行、測試套件執行或測試案例。舉例來說，測試架構目前會收集每個測試案例的 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 產生的輸出內容符合輸出格式。
效能注意事項
產生這種格式的檔案應該不會花費太多時間。儲存含有 10 萬個測試案例的套件 (每個案例都有 stdout 和 stderr 構件) 的原型實作，產生及保存 run_summary.json 的時間不到一秒，磁碟空間約為 26 MB。假設有 1,000,000 個案例，產生相同的原型大約需要 15 秒，run_summary.json在磁碟上約為 256 MB。在所有情況下，原型記憶體用量上限約為磁碟上摘要大小的兩倍。
相較之下，chromium 中已知的大型測試套件包含約 10 萬個測試案例。由於儲存這麼多案件的 run_summary.json 只需要不到一秒，因此應該不會有問題。
在 fuchsia.git 中，目前最大的測試套件包含約 300 到 400 個測試案例，而單一基礎架構分片可能包含約 300 個套件。對於 fuchsia.git，我們打算使用 ffx 測試的多重測試功能，將所有測試案例的結果儲存在單一輸出目錄中。因此在本例中，我們應預期 run_summary.json 最多會有約 12 萬個案件，估計在磁碟上佔用的空間不到 50 MB，儲存時間約為一秒。
開發人員經常會重複執行測試，舉例來說，開發人員可能會重複執行測試，以重現不穩定的失敗情況。在這種情況下，我們可輕鬆執行數千個測試案例批次，且不會超過 10 MB 的記憶體用量。
安全性考量
這項輸出內容僅用於儲存測試產生的結果和構件，且測試架構已提供這些內容，因此不會產生額外的安全性考量。
隱私權注意事項
這項輸出內容僅用於儲存測試產生的結果和構件，且測試架構已提供這些內容，因此不會產生額外的隱私權考量。
缺點和替代方案
輸出格式預設支援多個測試套件執行作業。這會讓一次只執行一項測試的用戶端，在剖析時變得更加複雜。其中一個替代方案是支援輸出格式，其中包含單一測試套件執行的結果，以及包含多個測試套件執行的結果的第二個輸出格式。雖然這樣可簡化即時剖析作業，但多種格式會讓分析輸出的共用工具變得複雜。
您也可以使用多個 JSON 檔案儲存測試結果。使用單一檔案儲存所有測試結果的缺點之一，是與該檔案互動的工具必須一次將所有內容保留在記憶體中。從原型來看，run_summary.json 大約需要 400 萬個測試案例才會超過 1 GB，此時序列化大約需要一分鐘。由於我們目前的使用案例比這個數量少一個數量級，因此還不需要多個檔案。由於將結果儲存在多個檔案中會使剖析作業變得複雜，因此我們將使用單一檔案。
第三種替代方案是將所有構件儲存在 run_summary.json 中，進一步簡化剖析作業。但缺點是構件現在也需要保留在記憶體中。今天收集到的最大構件是涵蓋範圍所用的設定檔資料。在單一基礎架構分片中，這個設定檔資料約為 500 MB，會分割成多個檔案。雖然這個設定檔未超過 1 GB，但測試分片方式和設定檔資料表示方式的組合變更，可能會迅速使大小接近 1 GB。