RFC-0164：Test Suite API

RFC-0164：測試套件 API
狀態已接受
區域
  • 測試
說明

API 審查，將套件通訊協定發布至 SDK
Gerrit 變更
作者
審查人員
提交日期 (年-月-日)2022-03-07
審查日期 (年-月-日)2022-05-05

編輯這份 RFC

編輯 RFC 中繼資料

舊版 API 設計文件

這份 RFC 先前以 API 設計文件形式提交，API 設計文件範本淘汰後，才轉換為 RFC。

目標和用途

  • 這項 API 或 API 功能解決了什麼問題？您的 API 使用者可以完成哪些工作？
    • 這個 API 會將所有測試功能 (列舉、執行、觀察) 封裝至 FIDL 通訊協定。
    • Fuchsia 可透過通用介面，使用統一的 UX 列舉及執行 Fuchsia 上的 POSIX 測試。
    • 可讓 Fuchsia 執行測試，並從各種測試架構中擷取標準結構化輸出內容。
    • 如要執行 Cfv2 元件並取得狀態，該元件必須公開某些能力。這個 API 提供良好的介面，可封裝測試執行階段，並將其公開為 Fuchsia 能力。
    • OOT 樹狀結構客戶需要建構及執行樹狀結構內沒有的測試，因此向 SDK 公開這個 API 可讓他們實作通訊協定，並自備執行階段進行測試。

設計

  • API 的實際程式碼定義，例如介面的 FIDL 定義。
  • 包含 API 程式碼的 Gerrit 變更連結：
  • 設計規定
    • 執行測試，瞭解目前 Fuchsia 樹狀結構中常用的測試套件。
    • 將測試結果表示為結構化資料，而不是 stdout 的字元串流、處理程序回傳代碼，以及系統上的各種副作用。
    • 避免過度配合特定執行階段和測試架構。
    • 應輕鬆支援新語言和測試架構。
    • 協助進行 CFv2 遷移作業
    • 支援 Cfv2 測試。
  • 非目標：
    • 重新定義/改造測試。
      BYOR 代表開發人員會自備概念、架構和期望。我們的角色是配合。

不明

在早期設計階段，我們研究了主機端控制器和測試執行器之間通訊協定的先前技術。我們發現先前技術過度依賴產品或執行階段的特定假設。舉例來說，Android Jetpack 和 google3 Nitrogen 會採用 Android APK 和 JUnit 語意，說明測試類別、方法、註解、結果、錯誤等。

我們根據語言和測試架構 (gtest、Rust、Dart、JUnit、pytest) 的一般知識設計了這項功能。我們在腦中檢查過，確認可以為這些範例實作用戶端和伺服器，並為 C++ gtest、Rust 和 Golang 實作可運作的範例。

我們不知道自己不知道什麼，因此預計未來會繼續修訂這項通訊協定。

可用性

本節將回答下列有關 API 可用性的問題：

  • API 的語意是否可從簽章直覺判斷？
    • 是
  • 您是否已設計適當的擴充點，以便日後演進 API？
    • 是
  • 您的 API 行為是否與其他執行類似作業的 Fuchsia API 相似？
    • 否，Fuchsia 沒有這類 API，無法在細微層級執行測試並傳回結構化結果。
  • 與其他平台的類似 API 相比，您的 API 行為如何？
    • 不適用

我們以 C++ 和 Rust 兩種語言實作端對端使用範例，展現可用性和一般性

測試

  • 您打算如何測試 API？
    • 這項 FIDL API 的實作項目在 Rust 和 C++ 中都有廣泛的測試。
  • 如果開發人員要使用您的 API 功能，該如何測試程式碼？
    • 這項實作基本上會實作執行測試的機制。 開發人員應撰寫
    • 單元測試，用於測試內部程式碼。
    • 整合測試，確保實作項目與架構一致運作。

效能注意事項

  • 您的 API 是否涉及大量跨程序或執行緒界線的往返？
    • 否
  • 您的 API 是否涉及遠端程序或執行緒的封鎖？
    • 否
  • 您的 API 是否涉及複製大量資料？
    • 可以，但必須使用通訊端和迭代器。
  • 您預期 API 每秒會收到多少查詢次數 (QPS)？
    • 每項測試都會透過測試執行元件實作並公開這個通訊協定，並在測試執行完成後拆除。每個測試用戶端的查詢次數取決於測試案例數量和輸送量。
  • 您預期一般查詢會傳輸多少資料？
    • 如果是列舉 API，每次疊代可傳輸的資料量相當於 FIDL 大小上限。其餘 API 傳輸的資料量較小，只有幾 KB。

安全性考量

  • 您的 API 是否會公開安全防護相關的機密資訊？
    • 否
  • 您的 API 是否允許使用者操控安全性敏感資源？
    • 否
  • API 使用者是否彼此隔離？
    • 是 (如果按照 API 設計導入)。
  • 您的 API 是否遵守物件能力規範？
    • 是
  • 您的 API 是否鼓勵使用者安全地使用 API？
    • 您的 API 是否會導致檢查時間與使用時間 (TOCTOU) 安全漏洞？
    • 否，但不需要，因為我們只能使用這個 API 執行測試
    • 您的 API 是否清楚區分控制層和資料層？
    • 是

隱私權注意事項

  • 您的 API 是否會公開私密資訊？
    • 否
  • 您的 API 是否涉及任何個人識別資訊？
    • 否
  • 您的 API 是否涉及任何裝置 ID？
    • 否
  • 您的 API 是否允許使用者控管資訊分享方式？
    • 我們不會分享任何使用者資訊。

測試並非互動式使用者程式。不會出貨給消費者。 開發人員會在完全屬於自己的裝置上，或從共用裝置池借用並在歸還前清除資料的裝置上，叫用測試。

缺點和替代方案

我們可以繼續使用 Cfv1 設計執行測試，但這會大幅限制我們提供結構化測試結果的能力，以及將各種測試和對應的正式版元件遷移至 Cfv2。