| RFC-0141：CTF 程序 | |
|---|---|
| 狀態 | 已接受 |
| 區域 |
|
| 說明 | 說明如何讓 CTF 測試涵蓋所有測試案例。 |
| Gerrit 變更 | |
| 作者 | |
| 審查人員 | |
| 提交日期 (年-月-日) | 2021-09-20 |
| 審查日期 (年-月-日) | 2021-11-15 |
摘要
Fuchsia 相容性測試 (CTF) 現在會在提交佇列 (CQ) 中執行，確保新平台程式碼不會破壞回溯相容性。不過，測試套件的品質取決於其中包含的測試，而我們的測試套件只包含少數測試。本文件概述了平台的 CTF 計畫，以便取得完整的 API 和 ABI 涵蓋率。
提振精神
CTF 的用途在於判斷在特定裝置上執行的 Fuchsia 平台版本，是否正確實作 (或與) 特定 Fuchsia SDK 公開的 API 和 ABI。換句話說，這表示建構作業已正確實作 Fuchsia。
如果執行 Fuchsia 的系統通過特定 ABI 修訂版本的 CTF 測試，開發人員就能確信為該修訂版本建構的元件會在系統上運作，且系統與該修訂版本相容。我們會在 CQ 系統中執行與特定 ABI 和 API 修訂版本相關的測試。
Fuchsia 軟體開發套件 (SDK) 包含工具、程式庫和標頭，可讓開發人員指定 Fuchsia 的 API 和 ABI。我們將透過 SDK 向樹狀結構外開發人員公開的 API 和 ABI 稱為平台表面區域 (PlaSA)。每個 SDK 都搭配一組 CTF 測試，可測試其公開的表面區域。測試可提供原始和二進位檔形式。
為了讓這套系統發揮價值，我們必須提供完整且可靠的測試組合。可靠的測試可重複執行，可讓開發人員輕鬆找出所測試的平台行為，且不會出現不穩定的情況。如果一組測試能執行該介面所有已記錄的行為，則表示測試已完成。
截至 2021 年 9 月，CTF 套件中有幾項測試。在本文的其餘部分，我們會說明如何隨著時間建構完整且可靠的測試組合。
我們發現，在各團隊如何建立涵蓋範圍的過程中，有許多問題並未在本 RFC 中提及。舉例來說，我們並未特別說明如何追蹤進度，也不提供實作指南。這些問題超出範圍；如有必要，後續 RFC 會處理這些問題。
相關人員
這個部分會在稍後填寫。
協助人員：
FEC 指派的人員，負責引導這項 RFC 通過 RFC 程序。
審查者：
shayba@google.com，測試元件和程式庫 ananthak@google.com，測試基礎架構 abarth@google.com，Fuchsia TL
列出 FEC 在決定是否接受或拒絕此 RFC 時，會考慮的投票人 (+1 或 -1)。
諮詢：
列出應審查 RFC 但不需要核准的人員。
社會化：
這份文件已與 CTF 和測試基礎架構團隊分享。
設計
需求條件
我們有兩項基本規定，用於制定 CTF 政策。
首先，CTF 測試應長期提供 PlaSA 的完整涵蓋範圍，其中包含 ABI (目前定義為 Fuchsia 系統介面中的任何項目) 和 API (目前定義為需要 API Review +1 的任何項目)，並透過 SDK 向最終開發人員公開，以及預期的工具行為。下一節將討論涵蓋率的構成要素。
其次，CTF 測試應盡可能涵蓋 PlaSA 的預期用途和實際用途。我們需要涵蓋實際情況，因為如果測試未反映開發人員如何使用表面區域元素，我們就無法聲稱測試提供的任何相容性程度。我們需要涵蓋預期的案例，原因有兩個：首先，開發人員初次編寫 API 時，只會提供預期用途。其次，我們認為開發人員在開發 API 時，編寫預期的用戶端程式碼是一項實用的練習。
在本節中，我們將說明如何透過 CTF 提供廣泛的平台涵蓋率。
涵蓋率
在討論平台達到完整涵蓋率的意義之前，我們先來討論 CTF 的涵蓋率。
請注意，在本文件中，「完整涵蓋率」並非指必須執行所有可能的行為，而是指必須執行所有已記錄的行為 (包括成功和錯誤情況) 以及所有介面。非正式的說法是，每個測試練習的介面稱為元素。
CTF 團隊正在追蹤透過 SDK 匯出的 FIDL 和 C++ 方法涵蓋率。團隊將推動一項程序，確保我們涵蓋每個 FIDL 和 C/C++ 方法，且測試程式碼涵蓋 SDK 隨附的程式碼 (例如 libfdio 中的程式碼)。在本文件中，當我們提到「全覆蓋率」時，是指 CTF 計畫追蹤的範圍。
非 CTF 的測試不會計入涵蓋率。專屬測試 (也就是未公開且屬於 Fuchsia 平台的測試) 也不會計入涵蓋率。
請注意，完整涵蓋率並不能保證所有 API 的測試品質和實用性。CTF 程式不會追蹤許多內容，例如，我們無法讓測試執行每個可能的參數值組合 (每個採用 32 位元整數的 API 可能有 2^32 個值；我們不太可能以 2^32 個可能的測試執行這項操作)。因此，API 開發人員和審查人員有責任確保我們提供高品質的涵蓋率。
換句話說，CTF 是一種機制，可協助我們強制相容性，但本身並不足以達成目標。這項條件雖然必要，但不足以保證符合資格。
為確保涵蓋率品質，我們提供兩個大原則。開發人員可使用這些資訊，瞭解是否擁有足夠的涵蓋率。
首先，透過 PlaSA 公開的每項行為都應依照 API 說明文件大綱進行說明，並且應有可保證該行為的測試。舉例來說，說明文件大綱指出，應記錄參數為空值時的行為。應使用 CTF 測試來執行這項行為。
請注意，許多 API 均不符合說明文件大綱。我們建議您在開發 API 時編寫測試，因此在編寫這類測試的過程中，不妨順便充實說明文件，確保其符合評分標準規定。
其次，如果行為變更導致應用程式程式碼在樹狀結構外執行時出現回歸現象，則很可能缺少 CTF 測試。CTF 測試應可保證新版本的行為與舊版本相容。如果 Fuchsia 版本構建與舊版相容，則該版本構建必須能夠執行以該版本為目標的軟體。因此，如果變更導致回歸，導致應用程式程式碼無法在樹狀結構外執行，就會出現未經測試的相容性行為，也就是缺少 CTF 測試。
在某些情況下，平台行為可能會變更，以便更符合說明文件。在這種情況下，變更應會隨附新的 CTF 測試。
平台行為的變更也可能來自未記錄的行為變更，而我們希望這些行為保持未記錄狀態。我們在這種情況下採取的行動不在本文的討論範圍內。CTF 測試不應刻意執行未記錄的行為。
CTF 層級
為了鼓勵盡可能提高 CTF 涵蓋率，我們會逐步推出更多 CTF 涵蓋率相關規定。隨著區域的涵蓋率提升，會從較低的涵蓋率層級移至較高的涵蓋率層級。在新增測試之前，區域並未歸入任何等級。
特定層級的特定政策會以引號框標示：
這是非規範性文字。
這是規範性文字。
級別 1 (起步)
處理中斷情形
由於 CTF 的其中一項目標是確保相容性，而相容性不佳的關鍵徵兆，就是平台或 SDK 版本因行為變更而導致客戶無法正常使用，因此我們建議盡快導入下列政策：
如果平台或 SDK 版本導致 SDK 回溯失敗，或因 Fuchsia PlaSA API 或行為的回溯相容性變更而導致 Canary 版本失敗，則該重大變更的作者必須負責確保有新行為的相關文件，以及涵蓋新行為的 CTF 測試。如果目前無法為該表面區域元素編寫 CTF 測試，則擁有該 PlaSA 元素的團隊必須優先規劃相關開發作業。
如果行為是為了不記錄，則可授予上述例外狀況。例外狀況可能包括記錄行為是故意未記錄的事實，或是為使用者提供工具，協助他們找出自己依賴未記錄行為的事實。
新的 SDK 面向功能
我們希望開發人員能開始開發平台測試功能，並搭配新的 SDK 面向功能。
合作夥伴或公開 SDK 提供的 PlaSA 所有新增內容 (例如新的 SDK 工具、FIDL 通訊協定或方法，以及 C++ 標頭) 都需要進行 CTF 測試。凡是透過 API 審查取得新 API 元素，並將其納入公開或合作夥伴 SDK 的開發人員，都必須規劃如何在新的 API 中加入 CTF 測試。
負責平台變更的平台團隊有責任提供 CTF 測試，並與 CTF 計畫合作，以便提供該測試。
在 API 開發人員執行測試計畫時，強烈建議他們向 API 審查人員說明要撰寫哪些類型的測試，以便雙方共同理解測試計畫，包括哪些測試具有最高優先順序。
如果平台團隊會針對您擁有的 API 和 ABI 進行所有破壞向後相容性的變更，並為新的平台合約功能和行為編寫測試，則該團隊屬於第 1 級。
請注意，API 審查的 CTF 測試規定僅適用於 PlaSA API 元素。只要 API 未透過 SDK 向最終開發人員公開，就不需要相關的 CTF 測試。
第 2 級 (大樓)
API/ABI 演進
由於變更程式碼的損壞機率高於長期穩定的程式碼，且這也是提供逐步涵蓋率的方式，因此我們建議導入下列政策：
無論是新的 PlaSA 元素或現有元素，只要修改 PlaSA 元素的 API 或行為，都必須搭配涵蓋變更的 CTF 測試。
如果目前無法為現有的公開或合作夥伴介面元素編寫 CTF 測試，則負責團隊必須在變更前提供開發這些測試的計畫，並盡可能在與 API 審查人員達成協議後，立即執行該計畫。
在這個層級，無論新程式碼是否旨在變更 PlaSA 行為，強烈建議您在大幅重寫或替換任何影響 PlaSA 行為的服務、工具或程式庫之前，先編寫 CTF 測試。舉例來說，如果我們要從頭重寫核心，但保留相同的 VDSO 行為，則應在重寫前先編寫該行為的測試。
如果您已完成第 1 級所需的所有工作，並確保 CTF 測試涵蓋您對 ABI 或 API 所做的所有變更，就已達到第 2 級。
第 3 級 (完成)
長尾
我們知道許多 PlaSA 元素都經過長期測試，且許多元素並未在積極開發中。最終目標是為整個 PlaSA 提供涵蓋率。
每個領域都必須制定計畫，全面涵蓋所擁有的 PlaSA 元素，並提供該計畫的結果。
如果您已完成所有 Tier 2 所需事項，且已完整涵蓋您擁有的 PlaSA 元素，就算完成。
實作
Fuchsia 團隊將啟動 CTF 計畫，鼓勵全面涵蓋平台。系統會透過多個資訊主頁追蹤 CTF 涵蓋率。這些資訊主頁的詳細資料會不斷更新，且不在本 RFC 的範圍內，但會追蹤每個 PlaSA 元素的基本測試涵蓋率。
CTF 團隊負責為開發人員提供執行測試所需的基礎架構。如果測試開發人員找不到所需的功能，應與 CTF 團隊合作，確保他們能提供可在 CTF 基礎架構中執行的測試。開發人員可以回報錯誤，與 CTF 團隊聯絡。
API 審查也會隨之調整，以符合 CTF 測試必須隨變更而變動的規定。如果是第 2 級或更高等級的地區，則必須對 PlaSA 元素進行 CTF 測試，才能進行修改或新增。這項規定最終會擴及所有地區；屆時，我們預計會將測試納入 API 審查程序。
成效
測試不會影響平台效能。我們必須仔細追蹤 CTF 測試的機器用量，確保這些測試不會超過 Fuchsia 機器的容量。
人體工學
CTF 團隊的任務是確保各區域都能輕鬆編寫基本 CTF 測試，並且有執行這些測試的基礎架構。但不負責特定領域的基礎架構和架構。
回溯相容性
這項提案不會破壞回溯相容性。目標是建立機制，以便強制執行 Fuchsia 平台的回溯相容性。
安全性考量
我們認為 CTF 計畫不會對 Fuchsia 安全性造成負面影響。
隱私權注意事項
我們認為 CTF 計畫不會對 Fuchsia 的隱私權資源造成負面影響。
測試
由於本 RFC 主要詳述程序，因此不需要詳細的測試計畫。
說明文件
該團隊將與 DevRel 和技術作家合作，提供詳細且實用的指引，說明如何編寫有效的 CTF 測試。
缺點、替代方案和未知事項
這項異動會為 API 開發人員帶來大量前置工作，因為他們通常不會在 API 變更中加入測試。我們認為，要求開發人員在發布前編寫使用 API 的測試，有助於改善這些 API 的人體工學。
既有技術與參考資料
在開發新的 API 時，Android 系統也有類似的 CTF 納入程序。
許多程式設計語言也對新 API 有類似的測試要求。