| RFC-0141：CTF 流程 | |
|---|---|
| 状态 | 已接受 |
| 区域 |
|
| 说明 | 介绍了将 CTF 测试驱动到完全覆盖的过程。 |
| Gerrit 更改 | |
| 作者 | |
| 审核人 | |
| 提交日期（年-月-日） | 2021-09-20 |
| 审核日期（年-月-日） | 2021-11-15 |
摘要
Fuchsia 兼容性测试 (CTF) 现已在我们的提交队列 (CQ) 中运行，以确保新的平台代码不会破坏向后兼容性。不过，测试套件的质量取决于其中包含的测试，而我们的测试套件包含的测试很少。本文档概述了平台实现完整 API 和 ABI 覆盖率的 CTF 计划。
设计初衷
CTF 的存在是为了确定在特定设备上运行的 Fuchsia 平台 build 是否正确实现了（或兼容）特定 Fuchsia SDK 公开的 API 和 ABI。换句话说，它表明 build 正确实现了 Fuchsia。
如果运行 Fuchsia 的系统通过了特定 ABI 修订版本的 CTF 测试，那么其开发者可以确信，为该修订版本构建的组件将在该系统上正常运行，并且该系统向后兼容该修订版本。与我们关注的特定 ABI 和 API 修订版本相关联的测试会在我们的 CQ 系统中运行。
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
列出在决定是否接受或拒绝此 RFC 时，FEC 会考虑其投票（+1 或 -1）的人员。
已咨询：
列出应审核 RFC 但无需批准的人员。
共同化：
此文档已与 CTF 和测试基础架构团队分享。
设计
要求
我们有两项基本要求来驱动 CTF 政策。
首先，从长远来看，CTF 测试应全面覆盖 PlaSA，后者包含通过 SDK 向最终开发者公开的 ABI（目前定义为 Fuchsia 系统接口中的任何内容）和 API（目前定义为需要 API 审核 +1 的任何内容），以及预期工具行为。有关覆盖率的讨论，请参阅下一部分。
其次，CTF 测试应尽可能涵盖 PlaSA 的预期用例和实际用例。我们需要涵盖实际应用场景，因为如果测试不能反映开发者对 Surface Area 元素的操作，我们就无法声称测试提供了任何程度的兼容性。我们需要涵盖预期的情况，原因有两点。首先，当开发者首次编写 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 是一种有助于我们强制执行兼容性的机制，但仅靠它是不够的。这是必要的，但还不够。
为确保覆盖面质量，我们提供了两条经验法则。开发者可使用这些指标来了解其应用是否具有足够的覆盖率。
首先，根据 API 文档评分标准，通过 PlaSA 公开的每种应记录的行为都应有一个测试来保证该行为。例如，文档评分标准规定，当形参为 null 时，行为应记录在文档中。应通过 CTF 测试来练习该行为。
请注意，许多 API 不符合文档评分标准。由于我们鼓励在 API 开发过程中编写测试，因此编写此类测试的过程是完善文档并确保其符合评分标准要求的好时机。
其次，如果行为变更导致在树外运行的应用代码出现回归，则很可能缺少 CTF 测试。CTF 测试旨在保证新版本表现出与旧版本兼容的行为。如果某个 Fuchsia build 与旧版兼容，则该 build 必须能够运行以该版本为目标的软件。因此，如果某项更改导致了回归，从而破坏了在树外运行的应用代码，则说明存在未经过测试的兼容性行为，即缺少 CTF 测试。
在某些情况下，平台行为可能会发生变化，以使平台行为更好地符合文档。在这种情况下，相应更改应附带新的 CTF 测试。
平台行为的更改也可能源于对我们希望保持未载明的行为所做的更改。这种情况下的处理方式不在本文档的讨论范围内。CTF 测试不应故意测试未记录的行为。
CTF 层级
为了尽可能扩大 CTF 覆盖面，我们将逐步推出更多 CTF 覆盖面要求。随着区域扩大覆盖范围，它们会从覆盖范围较小的层级转移到覆盖范围较大的层级。在添加测试之前，区域不属于任何层级。
给定层级的具体政策以引用块的形式设置：
这是非规范性文本。
这是规范性文本。
第 1 层级（初始）
弥补中断
由于 CTF 的目标之一是确保兼容性，而平台或 SDK 版本因行为变化而导致客户中断是严重的不兼容性迹象，因此我们建议尽快引入以下政策：
如果平台或 SDK 版本因对 Fuchsia PlaSA API 或行为的向后不兼容更改而导致 SDK 回滚失败或 Canary 版本发布失败，则相应重大更改的作者负责确保新行为有文档记录，并且有涵盖新行为的 CTF 测试。如果目前无法为该界面区域元素编写 CTF 测试，则负责该 PlaSA 元素的团队必须优先制定开发计划。
如果该行为有意不记录在文档中，则可以授予上述例外情况。例外情况可能包括记录行为故意未记录的事实，或向用户提供工具以帮助他们识别自己依赖于未记录的行为。
面向 SDK 的新功能
我们希望开发者在开发面向新 SDK 的功能的同时，开始开发平台测试功能。
所有添加到 PlaSA 中的内容（例如新的 SDK 工具、FIDL 协议或方法以及 C++ 标头）如果随合作伙伴或公共 SDK 一起发布，都需要进行 CTF 测试。任何通过 API 审核并将其纳入公共或合作伙伴 SDK 的新 API 元素都必须制定计划，以便在新 API 中包含 CTF 测试。
负责平台变更的平台团队有责任提供 CTF 测试，并与 CTF 计划合作交付该测试。
在 API 开发者完成测试计划的过程中，我们强烈建议他们向 API 审核者说明他们打算编写哪些类型的测试，以便双方对测试计划达成共识，包括哪些测试的优先级最高。
如果平台团队针对您拥有的 API 和 ABI 的所有向后不兼容的变更都进行了测试，并为新的平台合约功能和行为编写了测试，则该团队属于第 1 级。
请注意，API 审核的 CTF 测试要求仅适用于 PlaSA API 元素。只要 API 未通过 SDK 向最终开发者公开，就不需要关联的 CTF 测试。
第 2 层级（建筑物）
API/ABI 演变
由于更改代码时出现中断的可能性高于长期稳定代码，并且为了提供增量覆盖率，我们建议引入以下政策：
对 PlaSA 元素（无论是新的还是现有的）的 API 或行为所做的所有修改都必须附带涵盖相应变更的 CTF 测试。
如果目前无法为现有的公开或合作伙伴 Surface Area 元素编写 CTF 测试，则负责团队必须在进行更改之前提供开发这些测试的计划，并尽快执行该计划（与 API 审核人员达成一致）。
在此层级，我们强烈建议在对任何会影响 PlaSA 行为的服务、工具或库进行重大重写或替换之前，先编写 CTF 测试，无论新代码是否旨在更改该行为。例如，如果我们从头开始重写内核，但保持相同的 VDSO 行为，则应在重写之前编写该行为的测试。
如果您完成了第 1 层的全部要求，并确保您对 ABI 或 API 所做的所有更改都包含在 CTF 测试中，那么您就达到了第 2 层。
第 3 级（完整）
长尾
我们认识到，有许多长期稳定的 PlaSA 元素，其中许多元素并未处于积极的开发阶段。最终，我们希望覆盖整个 PlaSA。
每个领域都必须制定一项计划，以全面覆盖其拥有的 PlaSA 元素，并交付该计划的结果。
如果您完成了第 2 级所需的一切，并且您拥有的 PlaSA 元素覆盖范围完整，那么您就完成了。
实现
Fuchsia 团队将启动 CTF 计划，以鼓励实现全面的平台覆盖。我们将通过多个信息中心跟踪 CTF 覆盖率。这些信息中心的详细信息会不断变化，并且超出了本 RFC 的范围，但它们会跟踪每个 PlaSA 元素的基本测试覆盖率。
CTF 团队负责为开发者提供运行测试所需的基础设施。如果测试开发者没有看到所需的功能，应与 CTF 团队合作，确保他们能够提供可在 CTF 基础架构中运行的测试。开发者可以提交 bug 来联系 CTF 团队。
API 审核流程也会不断改进，以满足 CTF 测试随更改一起提交的要求。对于 Tier 2 或更高级别的区域，对 PlaSA 元素的修改或添加必须有 CTF 测试。最终，此要求将扩展到所有领域；届时，我们预计会将测试正式纳入 API 审核流程。
性能
测试的存在不会影响平台性能。我们必须仔细跟踪 CTF 测试的机器使用情况，以确保它们不会超出 Fuchsia 机器容量。
工效学设计
CTF 团队的任务是确保各领域能够轻松编写基本 CTF 测试，并确保存在运行这些测试的基础设施。它们不负责特定于网域的基础设施和框架。
向后兼容性
此提案不会破坏向后兼容性。目标是创建一种机制，以强制执行 Fuchsia 平台的向后兼容性。
安全注意事项
我们认为 CTF 计划不会对 Fuchsia 安全性产生负面影响。
隐私注意事项
我们认为 CTF 计划不会对 Fuchsia 隐私权属性产生负面影响。
测试
由于此 RFC 主要详细说明了一个流程，因此不需要详细的测试计划。
文档
该团队将与 DevRel 和技术文档撰写人员合作，提供有关如何编写有效的 CTF 测试的详细实用指南。
缺点、替代方案和未知因素
此变更会给 API 开发者带来大量前期工作，而他们通常不会在 API 变更中包含测试。我们认为，要求开发者在发布 API 之前先编写使用这些 API 的测试，有助于在发布之前改进这些 API 的人机工程学。
在先技术和参考资料
在开发新 API 时，Android 系统也有类似的 CTF 包含流程。
许多编程语言对新 API 也有类似的测试要求。