RFC-0202：測試管理員服務

摘要

目前在 Fuchsia 上執行的測試是 Test Manager 的動態子項。 這項設計可讓測試管理工具在任何領域啟動測試 (產品擁有者有權建立)，因此測試作者可以轉送必要的執行器和功能，而不必變更測試管理工具。

提振精神

Test Manager 會以動態子項的形式啟動測試，並提供各種密封/非密封功能和樹狀結構內執行器。目前 Test Manager 的設計是使用一組靜態的內建測試執行器和測試領域執行。這項功能不允許樹狀結構外 (OOT) 和樹狀結構內客戶納入自己的測試執行器和必要功能，但隨著客戶增加，我們需要支援他們的用途。本文件建議「Test Manager 即服務」，讓客戶在選擇的測試領域 (可能位於 Test Manager 領域之外) 執行測試。這可減輕測試管理員的負擔，不必再將必要的系統功能路徑傳送至測試。

利害關係人

協助人員：davemoore@google.com

審查人員：geb@google.com、shayba@google.com、richkadel@google.com、kjharland@google.com、crjohns@google.com、cgonyeo@google.com、aaronwood@google.com、satsukiu@google.com、xbhatnag@google.com、yaneury@google.com、hjfreyer@google.com、akbiggs@google.com

已諮詢：

針對能力路徑、架構和測試 API 的相關問題，我們諮詢了元件架構團隊。

社交：

這項 RFC 經過測試架構和元件架構團隊的設計審查。

設計

在這個設計中，產品負責人會決定測試的執行位置，而測試執行器 (ffx test/run-test-suite) 會將必要資訊傳遞至測試管理員。我們會在 RunBuilder 通訊協定中新增名為 AddSuiteInRealm 的方法，並傳遞必要領域資訊。

  AddSuiteInRealm(resource struct {
      // The realm which contains the collection to launch the test in
      realm client_end:fuchsia.component.Realm;
      // All offers from the realm to the test collection
      offers: Vec<Capabilities>
      // the test collection to launch the test in.
      test_collection: string

      // ... existing fields from AddSuite
  });

測試管理工具會使用上述資訊，透過 Realm Builder 在指定集合中啟動測試，同時提供獨立記錄器、涵蓋範圍集合、樹狀結構內執行器等，以支援測試執行。元件管理員會將 LifecycleController 和 RealmQuery 通訊協定 (範圍限定為「/」) 路由至測試執行者。

測試領域可由平台本身或產品擁有者使用現有/新機制授權。目前只有平台可以定義測試領域，而這項工作旨在普及測試領域的定義和管理。

這項設計假設有兩種使用者。

• 測試領域作者：這個使用者會建立並維護測試執行的領域 (他們應有權在拓撲中建立領域)。
• 測試作者：測試的作者，測試會在領域作者建立的領域中執行。

測試領域作者會建立測試領域、進行設定，並與建構工具整合，讓測試作者執行測試。他們必須在測試領域中安裝 Realm Builder 分片，才能執行這項操作。

測試領域範例：

{
  include: [
      "sys/component/realm_builder.shard.cml",
  ],
  collections: [
      // The collection to launch test in
      {
          name: "tests",
          environment: "#test_env",
          durability: "transient",
      },
  ],
  offer: [
      {
          protocol: [
              // Some system or mocked protocol
              "fuchsia.foo.bar",
              ...
          ],
          from: "parent",
          to: [
              "#tests",
          ],
      },
      ...
  ],
  environments: [
      {
          name: "test_env",
          extends: "realm",
          runners: [
              // Offer some OOT runner to the test
              {
                  runner: "fuchsia_oot_runner",
                  from: "parent",
              },
              // TODO(https://fxbug.dev/42063673): Abstract out into a shard.
              // This is important so that Realm Builder can work.
              {
                  runner: "realm_builder",
                  from: "#realm_builder_server",
              },
          ],
          resolvers: [
              // This is important so that Realm Builder can work.
              {
                  resolver: "realm_builder_resolver",
                  from: "#realm_builder_server",
                  scheme: "realm-builder",
              },
          ],
      },
  ]
}

領域作者會與建構工具整合，以便測試執行器在執行期間讀取路徑名稱和測試集合。

「人體工學」部分簡要介紹了將路徑名稱和測試集合名稱傳遞至測試執行器的解決方案，但詳細討論不在本文範圍內。

測試作者會使用其中一種人體工學解決方案 (待定) 執行測試，並將資訊傳遞給測試執行者來執行測試。

測試執行器會使用 RealmQuery API 查詢領域物件的領域和所有優惠，並透過提議的 AddSuiteInRealm API 將這些項目傳遞至 Test Manager。

如果需要，也會使用 LifecycleController API 解析路徑名稱。

這項設計必須進行下列變更：

• 修改 RealmQuery API，讀取「offer」宣告。
• Realm Builder Rust 用戶端程式庫會經過修改，允許使用提供的 fuchsia.component/Realm 代理項目建構領域。
• 測試管理工具會使用 Realm Builder 程式庫中的新方法，透過範圍限定於自訂領域的 Realm Builder 啟動測試例項。
• Test Manager 會使用提供的 offers，並透過 Realm Builder 傳送這些 offers。
• Test Manager 會在測試環境中設定獨立記錄器、偵錯資料通訊協定、樹狀結構內執行器等。

測試管理工具現在有元件執行個體的控制代碼，因此可以連線至測試領域的所有功能。

測試結束後，測試管理員會收集所有構件並上傳測試結果。測試可存取父項領域提供的任何能力，以及測試架構提供的所有密封功能。

這個方法的優點

• 開發人員可以自備執行器。
• 現在就能做到。不必等待任何其他功能。

其他福利

• 開發人員可以隨意設定測試領域，不必變更核心產品或測試架構。
• 不需要支援自訂測試類型。

這項解決方案的缺點如下：

• 開發人員可以建立自己的非密封領域來啟動測試，因此我們可能會得到一堆非密封測試，只要稍加努力，這些測試就能密封。
• 如果開發人員直接使用 ffx test，則須向工具提供路徑名稱和集合名稱。
  • ffx test 是基礎工具，因此開發人員應使用會呼叫 ffx test 的其他工具，不需要手動傳遞路徑名稱。

測試管理工具可做為服務使用，並提供測試拓撲圖。

實作

• 變更 Realm Builder，允許其透過接受 fuchsia.component.Realm 物件，在任意領域啟動元件。
• 變更測試執行器，接受領域資訊查詢所需資訊的路徑名稱。
• 變更 Test Manager，實作新的 FIDL API，並在提供的領域和集合中啟動測試。
• 記錄變更和說明指南
• 與 OOT 開發人員合作，建立包含 OOT 執行器的領域。
• 將目前的 OOT 測試移植到新領域

後續作業：

• 將使用自訂測試類型的現有測試移植到自己的領域。
• 探索如何移除對別名的依附性。
• 從測試管理員下方移除所有測試領域，並在產品領域中發布。

效能

這項異動不會影響測試啟動方式，只會影響測試在拓撲中的啟動位置，因此對效能的影響不大或沒有影響。

人體工學

本節說明如何將路徑名稱和測試集合傳遞至測試執行器。本文不提供詳細解決方案。

與建構作業整合

定義自訂領域後，產品擁有者即可在建構系統中定義測試類別。測試作者會使用該類別，而建構系統會產生相應的路徑名稱和測試集合，做為測試執行器的輸入內容。

在測試資訊清單中新增資訊

我們可以在測試構面中嵌入路徑名稱和測試集合資訊。測試執行器必須解析並讀取元件資訊清單檔案，才能取得資訊。

為提升人體工學，測試領域作者會提供資訊清單分片，測試作者可將這些分片納入測試資訊清單。

回溯相容性

我們會繼續支援目前的測試，並一律支援不需要自訂執行器的密封測試領域。

安全性考量

• 開發人員可以在系統中的任何領域啟動測試，但由於測試會在工程建構版本上執行，因此使用者裝置不會受到這項變更影響。
  • 測試執行器也會提供旗標，方便您在特定共用機器和建構作業中停用這項功能。
• 我們需要將 RealmQuery 和 LifecycleController 轉送至所有測試執行器。視我們決定如何執行這項操作而定，這可能涉及安全性疑慮。我們會在下一份文件討論如何設計測試執行人員的資訊存取權。

隱私權注意事項

我們不會收集任何個人資料，因此這項設計不會對隱私權造成任何影響。

測試

目前的測試，以及在自訂領域中啟動測試的新整合和單元測試，都應完整測試這項功能。

說明文件

記錄這項功能，說明用途和實作指南，供開發人員建立自己的測試領域。

此外，也請記錄測試開發人員使用自訂領域的方式。

缺點、替代方案和未知事項

替代方案：客戶自行啟動 Test Manager

測試開發人員會在拓撲中啟動自己的 Test Manager。ffx test 會使用 RCS 連線至 fuchsia.test.manager.RunBuilder 通訊協定，執行測試並收集結果。

這項解決方案的優點：

• 我們只需要變更 ffx 測試來支援這項功能
• 開發人員可以使用目前的 Test Manager 程式碼和自訂資訊清單，在拓撲中運用 Test Manager 元件

這個解決方案的問題如下：

• 一旦 Test Manager 在各種拓撲和 OOT 中執行，就很難變更。這會大幅影響測試架構團隊的開發速度。
• 用戶需要將測試管理員所需的所有功能，路徑設定至自己的拓撲。
• 客戶必須編寫測試，確保 Test Manager 在拓撲中正常運作，並避免發生迴歸問題

替代方案：子組合

子組合可以解決自備測試執行元件的問題，但不如建議的解決方案靈活。

這項解決方案可讓我們彈性地從測試管理員中移除所有硬式編碼測試領域，並將完整擁有權授予產品擁有者。

替代方案：測試會套件自己的執行器

測試可以套件自己的執行元件，並使用這些執行器執行測試元件

這項解決方案的優點：

• 不需要進行任何變更
• 現在就能達成

這個解決方案的問題如下：

• 為每項測試執行新執行元件的效能影響。
• 需要將執行元件所需的功能路徑傳送至測試 (會破壞密封性並削弱保證)。
• 您必須為每個新執行元件建立自訂領域 (因為能力路徑需求)。這會導致技術債不斷累積。

替代做法：測試設定

使用功能和這些功能的來源，將測試參數化，然後將這些參數傳送至測試領域本身。

"fuchsia.test.additional_capabilities": {
  "runner": "dart_runner",
  "source": "/core/dart/runner"
}

對於可路由傳送的功能，Test Manager 可以使用 RealmQuery API，透過 Realm Builder 代理要求。對於執行器，Test Manager 可以使用 Hub 做為執行器通訊協定的 Proxy。

這項解決方案的優點：

• 測試會以 Test Manager 的子項執行，因此 Test Manager 可全面控管其功能。

這個解決方案的問題如下：

• 測試可能會依附於正式版別名，因此會成為公開 API 的一部分。
• 使用中樞做為執行者要求的 Proxy 只是短期解決方案，我們最終需要巢狀或鏈結執行者。
• 測試可以存取任何系統能力，這可能會造成安全性問題，例如中斷明確的路由，或建立遠端動作。

替代方案：Test Manager 使用 RealmQuery API

在這個設計中，測試管理員可以存取 RealmQuery API，並使用該 API 從測試領域查詢必要資訊，以啟動測試。

測試作者會使用分片，在測試資訊清單中加入領域和測試集合資訊。

分片：

{
  facets: {
    "fuchsia.test": {
      launch: {
        realm: "/core/foo/bar/test_realm",
        collection: "tests" // default is "tests", can be omitted.
      }
    },
  },
}

test.cml:

{
    include: [
        "syslog/client.shard.cml",
        "//some/path/oot_runner/default.shard.cml",
        "//some/path/test_realm/default.shard.cml",
    ],
    program: {
        binary: "bin/sample_test",
    },
    use: [
      {
          protocol: [
              "fuchsia.foo.bar",
              ...
          ],
      },
      ...
  ],
}

測試管理員會讀取各個層面，並使用提供的能力在指定測試領域中查詢及啟動測試。

替代方案：Test Manager 會在拓撲中一個已知的位置執行系統測試

這項設計建議在拓撲中提供一個常見的已知位置 (例如 /core/tests)，供測試管理員執行所有系統測試。平台開發人員會建立及維護這個已知領域，而測試管理員只會提供機制，用於執行測試及收集測試中的構件。

缺點

• 可設定的項目較少，且日後如需在多個位置執行測試，就無法擴充。
• 我們希望日後能提供巢狀 Test Manager，在同層領域中執行測試。這種設計會阻礙這類行為。
• 我們可以運用這份 RFC 的設計，達到相同功能，並以 /core/tests 為目標，做為應執行測試的領域。我們相信這項 RFC 提供的彈性將十分實用。

既有技術和參考資料

這是 Fuchsia 獨有的概念，因此沒有相關的先前技術。

後續作業

• 從測試管理員拓撲中移除所有非密封領域，並與客戶合作，將測試移至他們自己的自訂測試領域。
• 設計「自備測試管理員」，做為測試領域的同層級項目。這項功能有助於在工作階段或任何 OOT 領域下執行測試，且不需要平台提供任何產品專屬支援。