| 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 测试配对，这些测试会执行其公开的表面积。 这些测试以源代码和二进制形式提供。
为了使此系统提供价值，我们必须拥有一套稳健、完整的测试。 稳健的测试是可重复的：它们让开发者能够轻松识别他们正在测试的平台行为，并且不会出现不稳定性。如果一套测试执行了该接口的所有已记录行为，则该套测试是完整的。
截至 2021 年 9 月，CTF 套件中只有少数测试。 在本文档的其余部分中，我们将介绍如何随着时间的推移构建一套稳健、完整的测试。
我们注意到，与每个团队如何构建覆盖率相关的许多流程问题未在此 RFC 中解决。 例如，我们如何跟踪进度未被明确指出，并且我们未提供实现指南。 这些问题超出了范围；如有必要，后续 RFC 将解决这些问题。
利益相关者
此部分将在稍后填写。
协调人：
FEC 指定的人员，负责引导此 RFC 完成 RFC 流程。
审核人：
shayba@google.com，测试组件和库 ananthak@google.com，测试基础架构 abarth@google.com，Fuchsia TL
列出其投票（+1 或 -1）将被 FEC 在决定是否接受或拒绝此 RFC 时考虑在内的人员。
咨询对象：
列出应审核 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 是一种帮助我们强制执行兼容性的机制，但它本身并不足够。 它是必要的，但并不充分。
为了确保高质量的覆盖范围，我们提供了两条经验法则。 开发者可以使用它们来了解他们是否拥有足够的覆盖范围。
首先，根据 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 的新功能的同时，开始开发平台测试功能。
合作伙伴或公共 SDK 附带的所有 PlaSA 添加项（例如，新的 SDK 工具、FIDL 协议或方法以及 C++ 标头）都需要 CTF 测试。任何通过 API 审核并将其包含在公共或合作伙伴 SDK 中的新 API 元素都必须制定计划，以便将 CTF 测试包含在其新 API 中。
拥有平台更改的平台团队有责任提供 CTF 测试，并与 CTF 计划合作交付该测试。
当 API 开发者完成其测试计划时，我们强烈建议他们向 API 审核人说明他们打算编写哪些类型的测试，以便他们能够对测试计划达成共识，包括哪些测试的优先级最高。
如果平台团队使用测试来响应您拥有的 API 和 ABI 的所有向后兼容性中断更改，并为新的平台合约功能和行为编写测试，则该团队属于第 1 层级。
请注意，API 审核的 CTF 测试要求仅适用于 PlaSA API 元素。 只要 API 未通过 SDK 向最终开发者公开，就不需要关联的 CTF 测试。
第 2 层级（构建）
API/ABI 演变
由于更改代码中的中断比长期稳定代码中的中断更常见，并且为了提供增量覆盖范围，我们建议引入以下政策：
对 PlaSA 元素的 API 或行为的所有修改（无论它是新的 PlaSA 元素还是现有元素）都必须附带涵盖该更改的 CTF 测试。
如果目前无法为现有的公共或合作伙伴表面积元素编写 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 主要详细介绍了流程，因此不需要详细的测试计划。
文档
该团队将与 DevRel 和技术撰稿人合作，提供有关如何编写有效的 CTF 测试的详细且有用的指南。
缺点、替代方案和未知因素
此更改为 API 开发者带来了大量前期工作，他们通常不会在其 API 更改中包含测试。 我们认为，要求开发者在发布 API 之前编写使用其 API 的测试将改善这些 API 在发布之前的工效学设计。
在先技术和参考资料
Android 系统在开发新 API 时也有类似的 CTF 包含流程。
许多编程语言对新 API 也有类似的测试要求。