编写和运行 Starnix 测试

本指南介绍了如何运行和编写 Starnix 的自动化测试。

1. 运行现有测试

验证 Starnix 中的功能或重现 bug 的推荐方法是编写和运行 C++ 系统调用测试。这些测试位于 //src/starnix/tests/syscalls/cpp/ 中。

如需运行现有测试，请配置包含 Starnix 测试目标的 Fuchsia build：

配置 build：

fx set workbench_eng.x64 \
    --with-test //src/starnix/tests/syscalls/cpp:starnix_syscalls_cpp_tests

构建 Fuchsia：
```
fx build
```
启动模拟器（或连接 Fuchsia 设备）。例如，如需在没有图形界面的情况下启动模拟器，请运行以下命令：
```
ffx emu start --headless
```
如需了解更多选项，请参阅 Fuchsia 模拟器说明。
运行测试：
```
fx test starnix_syscalls_cpp_tests
```

2. 编写新测试

添加新的系统调用或内核功能时，请在 //src/starnix/tests/syscalls/cpp/ 目录中添加相应的测试。

以下部分介绍了如何编写这些测试：

针对 Linux 内核进行测试：了解如何针对主机 Linux 内核进行交叉测试。
使用测试预期：了解如何处理 Starnix 中尚未实现的功能。
示例：创建新测试：了解创建新测试文件的示例。

针对 Linux 内核进行测试

Starnix 系统调用测试套件的目的是针对 Linux 内核对 Starnix 进行交叉测试。由于 Starnix 实现了 Linux UAPI，因此完全相同的测试二进制文件会在 Linux 和 Fuchsia 环境中编译和运行。这既验证了对 Linux 行为的理解，也验证了 Starnix 实现的准确性。

您可以通过以下两种方式针对 Linux 环境运行测试：

Machina（首选）：在 Linux 虚拟机内运行测试。这是推荐的方法，因为它使用我们的目标内核版本提供了一个隔离的标准化环境。不过，运行 Machina 需要基于 Intel 的 CPU 来执行。如需详细了解如何设置和使用 Machina，请参阅 Machina runtime for Linux testing。
宿主机测试（备用）：直接在 Linux 宿主机上运行测试。对于没有 Intel CPU 的用户，或者对于不依赖主机环境不支持的功能的简单测试，这是一种备用方法。请注意，您必须使用 GN 参数 starnix_force_build_host_tests = true 显式启用主机测试构建。

如果针对 Linux 环境运行测试时测试失败，则可能表明测试本身不正确，或者对 Linux 行为的假设是错误的。您应该先修复测试以使其在 Linux 上通过，然后再使用它来验证 Starnix。

如需编写新测试，请执行以下操作：

开发测试并针对 Linux 环境运行测试。
- 首选：使用 Machina（需要 Intel CPU）。请参阅 Machina runtime for Linux testing。
- 后备：运行主机测试。确保您的 build 配置为包含测试并强制构建主机测试：
```
fx set workbench_eng.x64 \
    --with-test //src/starnix/tests/syscalls/cpp:tests \
    --args='starnix_force_build_host_tests = true'
```
  然后，在 Linux 主机上运行测试。主机测试目标名称与目标测试名称相同，但以 starnix_ 为前缀，以 _host 为后缀。例如，如需运行 hello_starnix_test，请运行以下命令：
```
fx test starnix_hello_starnix_test_host
```
反复测试，直到测试在 Linux 环境中 100% 通过。
提交预期会失败的测试。如果 Starnix 中尚未完全实现系统调用，则 Starnix 测试目标将失败。您不应等待系统调用完成，而应使用测试预期（请参阅使用测试预期）添加预期失败，并将测试套件作为基准提交。
在 Starnix 中实现功能。在 Linux 上建立基准并通过后，开始在 Starnix 内核中实现系统调用。如需有关编写 Starnix 系统调用的指南，请参阅 Starnix syscall rubric 和 Common coding patterns。
针对 Starnix 运行测试。在连接 Fuchsia 设备或运行模拟器的情况下，运行测试：
```
fx test hello_starnix_test
```
迭代优化 Starnix 实现，直到测试通过。测试通过后，更新测试预期（请参阅使用测试预期）以移除预期失败。

使用测试预期

您在 Linux 主机上测试的某些系统调用可能尚未在 Starnix 中完全实现。如果测试在 Linux 上成功运行，但在 Starnix 上失败，则 Fuchsia build 将变为红色。Starnix 不会删除测试或等待系统调用完全构建，而是使用 测试预期 来明确记录哪些测试预期会失败。

找到预期文件：预期在 .json5 文件中定义（例如： //src/starnix/tests/syscalls/cpp/expectations/syscalls_cpp_test.json5）。

添加失败预期：将失败的测试块的名称添加到 expect_failure 列表中。

// expectations/syscalls_cpp_test.json5
{
    actions: [
        {
            type: "expect_failure",
            matchers: [
                // TODO(https://fxbug.dev/12345): Implement new sys_xyz
                "HelloStarnixTest.FailingTest",
            ],
        },
    ],
}

提交测试套件：提交包含失败预期的测试套件。这会将 Linux 行为确立为基准。
实现系统调用：在后续 CL 中，在 Starnix 中实现系统调用。
移除预期： Starnix 实现允许测试通过后，从 .json5 文件中删除条目。现在，该测试将充当回归保护。

示例：创建新测试

例如，如需创建名为 hello_starnix_test.cc 的新测试文件，该文件用于测试 Starnix 中尚未实现的系统调用，请执行以下操作：

创建 //src/starnix/tests/syscalls/cpp/hello_starnix_test.cc：

#include <gtest/gtest.h>

namespace {

TEST(HelloStarnixTest, Basic) {
  EXPECT_TRUE(true);
}

}  // namespace

在 //src/starnix/tests/syscalls/cpp/expectations/syscalls_cpp_test.json5中为测试添加失败预期：

// ... inside the file's `expect_failure` block:
{
    type: "expect_failure",
    matchers: [
        // ... existing expectations ...
        "HelloStarnixTest.Basic",
    ],
}

将 "hello_starnix_test" 添加到 syscall_tests 列表中 //src/starnix/tests/syscalls/cpp/BUILD.gn：
```
syscall_tests = [
  # ... other tests ...
  "hello_starnix_test",
  # ...
]
```
构建更新后的测试软件包：
```
fx build
```
在运行 Fuchsia 设备或模拟器的情况下，执行新测试：
```
fx test hello_starnix_test
```

由于在 .json5 文件中添加了预期，因此测试运行程序预期测试在 Starnix 上会失败。build 将成功，并且测试运行将报告为通过。在 Starnix 中实现缺失的系统调用后，您可以从 .json5 文件中移除预期。