RFC-0164：Test Suite API

RFC-0164：测试套件 API
状态已接受
区域
  • 测试
说明

API 审核：将 suite 协议发布到 SDK
Gerrit 更改
作者
审核人
提交日期（年-月-日）2022-03-07
审核日期（年-月-日）2022-05-05

修改此 RFC

修改 RFC 元数据

之前的 API 设计文档

此 RFC 之前以 API 设计文档的形式提交，后来在 API 设计文档模板被弃用后转换为 RFC。

目标和使用场景

  • 此 API 或 API 功能解决了什么问题？您的 API 的用户能够完成哪些任务？
    • 此 API 将所有测试功能（枚举、执行、观察）封装到 FIDL 协议中。
    • 允许 Fuchsia 提供一个通用接口，以便使用统一的用户体验在 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 是否涉及任何设备标识符？
    • 否
  • 您的 API 是否允许用户控制信息的分享方式？
    • 我们不会分享任何用户信息。

测试不是交互式用户程序。它们不会直接向消费者发货。 开发者会在自己完全拥有的设备上调用测试，或者在从共享池借用并会在返回到共享池之前擦除的设备上调用测试。

缺点和替代方案

我们可以继续使用 Cfv1 设计来执行测试，但这会严重限制我们提供结构化测试结果的能力，并限制我们迁移各种测试和相应的生产组件到 Cfv2。