| RFC-0141：CTF 流程 | |
|---|---|
| 状态 | 已接受 |
| 领域 |
|
| 说明 | 介绍了推动 CTF 测试全面覆盖的过程。 |
| Gerrit 更改 | |
| 作者 | |
| 审核人 |
|
| 提交日期（年-月-日） | 2021-09-20 |
| 审核日期（年-月-日） | 2021-11-15 |
总结
现在，针对 Fuchsia (CTF) 的兼容性测试正在我们的提交队列 (CQ) 中运行，以确保新的平台代码不会破坏向后兼容性。不过，测试套件的效果取决于其包含的测试，而我们的测试很少。本文档简要介绍了该平台的 CTF 计划，以便其全面覆盖 API 和 ABI。
设计初衷
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 测试配对，用于执行其公开的 Surface 区域。这些测试提供源代码和二进制文件形式。
为了让该系统提供价值，我们必须具有一套强大且完整的测试。稳健的测试可重复进行：借助这些测试，开发者可以轻松确定测试的平台行为，并且测试不会出现不稳定问题。如果这组测试执行了该接口的所有记录的行为，那么这组测试就完成了。
截至 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 的预期用例和实际用例。我们需要涵盖实际用例，因为如果测试不能反映开发者对表面区域元素执行的操作，我们不能声称测试能够提供任何程度的兼容性。我们之所以需要涵盖预期用例，原因有两个。首先，当开发者首次编写 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 文档评分准则记录的行为也应该有可保证该行为的测试。例如，文档评分准则规定，应记录参数为 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 测试。如果目前无法为该 surface 区域元素编写 CTF 测试，则拥有该 PlaSA 元素的团队必须优先制定计划来开发这些测试。
如果不记录该行为，则可以准许上述例外情况。例外情况可能包括记录行为未经记录这一事实，或向用户提供工具帮助他们识别他们依赖于未记录的行为这一事实。
面向 SDK 的新功能
我们预计开发者将开始开发平台测试功能以及面向 SDK 的新功能。
合作伙伴或公共 SDK 搭载的 PlaSA 的所有新增内容（例如新的 SDK 工具、FIDL 协议或方法，以及 C++ 头文件）都需要进行 CTF 测试。任何通过 API 审核接受新 API 元素并将其纳入公共 SDK 或合作伙伴 SDK 中的用户都可以制定将 CTF 测试纳入新 API 的计划。
负责平台变更的平台团队将负责提供 CTF 测试，并与 CTF 计划合作完成该测试。
在 API 开发者逐步完成测试计划的过程中，我们强烈建议他们向 API 审核人员说明自己打算编写的测试类型，以便他们对该测试计划达成共识，包括哪些测试的优先级最高。
如果平台团队通过测试回应了您对 API 和 ABI 的所有向后兼容性更改，并针对新的平台合同功能和行为编写了测试，则该团队属于第 1 层级。
请注意，针对 API 审核的 CTF 测试要求仅适用于 PlaSA API 元素。只要 API 未通过 SDK 向最终开发者公开，就不需要相关的 CTF 测试。
第 2 级（建筑物）
API/ABI 演变
由于破坏代码的可能性比破坏长期稳定代码的更可能，并且作为一种提供增量覆盖率的方式，我们提议引入以下政策：
对 API 或 PlaSA 元素行为所做的所有修改，无论是新的 PlaSA 元素还是现有元素，都必须伴随着涵盖更改的 CTF 测试。
如果目前无法为现有的公开或合作伙伴 Surface 区域元素编写 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 团队联系。
为适应 CTF 测试随变更的要求，API 审核也将不断完善。对于级别 2 或更高级别的区域，对 PlaSA 元素的修改或添加必须进行 CTF 测试。最终，此要求将扩展到所有方面；届时，我们希望在 API 审核过程中正式确定测试。
性能
测试的存在对平台性能没有影响。我们必须仔细跟踪 CTF 测试的机器使用情况，确保它们不会超出紫红色机器的容量。
工效学设计
CTF 团队负责确保相关领域可以轻松地编写基本的 CTF 测试，并拥有运行这些测试的基础架构。它们不负责特定于网域的基础架构和框架。
向后兼容性
此方案不会破坏向后兼容性。目标是打造一种机制来强制执行 Fuchsia 平台的向后兼容性。
安全注意事项
我们相信 CTF 计划不会对 Fuchsia 的安全性产生负面影响。
隐私注意事项
我们相信 CTF 计划不会对 Fuchsia 隐私属性产生负面影响。
测试
由于此 RFC 主要详细地介绍了一个流程，因此不需要详细的测试计划。
文档
该团队将与 DevRel 和技术文档工程师合作，针对如何编写有效的 CTF 测试提供详细而实用的指导。
缺点、替代方案和未知情况
对于 API 开发者来说，这一变更会产生大量前期工作，因为他们通常不会在 API 变更中包含测试。我们认为，要求开发者在发布 API 之前编写使用其 API 的测试，将在发布之前改进这些 API 的工效学设计。
早期技术和参考资料
在开发新 API 时，Android 系统也有类似的 CTF 收录流程。
许多编程语言对新 API 也有类似的测试要求。