| 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 的讨论范围之内；如果需要，后续 RFC 将对其进行讨论。
利益相关方
此部分稍后填写。
教员：
由 FEC 任命的负责引导此 RFC 完成 RFC 流程的人员。
Reviewers:
shayba@google.com，测试组件和库 ananthak@google.com，测试基础架构 abarth@google.com，Fuchsia TL
列出 FEC 在决定是否接受此 RFC 时会考虑其投票结果 (+1 或 -1) 的人员。
咨询了：
列出应审核 RFC 但无需获得其批准的人员。
社交：
此文档已与 CTF 和测试基础架构团队分享。
设计
要求
我们有两个基本要求，是 CTF 政策的依据。
首先，CTF 测试应从长远来看，对 PlaSA 提供完整的覆盖，其中包括 ABI（目前定义为 Fuchsia 系统接口中的任何内容）和 API（目前定义为需要 API 审核 +1 的任何内容），以及通过 SDK 向最终开发者公开的预期工具行为。下一部分将介绍什么是覆盖率。
其次，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 测试。如果目前无法为该 Surface Area 元素编写 CTF 测试，则拥有该 PlaSA 元素的团队必须优先制定开发这些测试的计划。
如果行为不打算记录，则可以授予上述行为的例外情况。此类例外情况可能涉及记录行为是故意不记录的事实，或者向用户提供工具，帮助他们发现自己在依赖未记录的行为。
面向 SDK 的新功能
我们希望开发者开始开发平台测试功能以及面向新 SDK 的功能。
与合作伙伴 SDK 或公共 SDK 一起分发的 PlaSA 中的所有新增内容（例如新的 SDK 工具、FIDL 协议或方法以及 C++ 头文件）都需要进行 CTF 测试。任何通过 API 审核并将新 API 元素纳入公共 SDK 或合作伙伴 SDK 的开发者都必须计划在其新 API 中添加 CTF 测试。
负责平台变更的平台团队有责任提供 CTF 测试，并与 CTF 计划合作来提供该测试。
在 API 开发者制定测试计划的过程中，我们强烈建议他们向 API 审核人员说明他们打算编写哪些类型的测试，以便双方对测试计划达成共识，包括哪些测试是优先级最高的。
如果平台团队针对您拥有的 API 和 ABI 的所有向后不兼容的更改做出回应，并针对新的平台协定功能和行为编写测试，则该团队属于第 1 层级。
请注意，针对 API 审核的 CTF 测试要求仅适用于 PlaSA API 元素。只要 API 未通过 SDK 公开给最终开发者，就无需关联的 CTF 测试。
第 2 层级（建筑物）
API/ABI 演变
由于更改型代码发生故障的可能性高于长期稳定型代码，并且为了提供增量覆盖率，我们建议引入以下政策：
对 PlaSA 元素的 API 或行为所做的所有修改（无论是新的 PlaSA 元素还是现有 PlaSA 元素）都必须附带涵盖相应更改的 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 测试随更改而更新的要求。对于第 2 级或更高级别的区域，对 PlaSA 元素进行修改或添加时，必须进行 CTF 测试。最终，此要求将扩展到所有地区；届时，我们预计会将测试正式纳入 API 审核流程。
性能
测试的存在对平台性能没有影响。我们必须仔细跟踪 CTF 测试的机器用量，确保其不会超出 Fuchsia 机器容量。
工效学设计
CTF 团队的任务是确保各个领域都能轻松编写基本 CTF 测试，并且存在用于运行这些测试的基础架构。它们不负责特定领域的基础架构和框架。
向后兼容性
此提案不会破坏向后兼容性。目标是创建一种机制，以强制执行 Fuchsia 平台的向后兼容性。
安全注意事项
我们认为 CTF 计划不会对 Fuchsia 安全性产生负面影响。
隐私注意事项
我们认为 CTF 计划不会对 Fuchsia 隐私保护属性产生负面影响。
测试
由于此 RFC 主要详细介绍了流程，因此不需要详细的测试计划。
文档
该团队将与开发者关系团队和技术文档撰写团队合作，就如何编写有效的 CTF 测试提供详细实用的指导。
缺点、替代方案和未知情况
这项变更会给 API 开发者带来大量前期工作，因为他们通常不会在 API 更改中添加测试。我们认为，要求开发者在发布 API 之前编写使用这些 API 的测试，有助于在发布前改进这些 API 的人体工学。
在先技术和参考文档
在开发新 API 时，Android 系统在 CTF 包含方面也有类似的流程。
许多编程语言对新 API 也有类似的测试要求。