撰寫及執行 Starnix 測試

本指南提供操作說明，協助您執行及編寫 Starnix 的自動化測試。

1. 執行現有測試

如要在 Starnix 中驗證功能或重現錯誤，建議您編寫及執行 C++ 系統呼叫測試。這些測試位於 //src/starnix/tests/syscalls/cpp/。

如要執行現有測試，請設定包含 Starnix 測試目標的 Fuchsia 建構作業：

設定版本：

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 實作了 Linux UAPI，因此會在 Linux 主機上編譯並執行完全相同的測試二進位檔，以驗證對 Linux 行為的瞭解程度。然後在 Fuchsia 上執行這些測試二進位檔，驗證 Starnix 的實作結果。

如果針對主機 Linux 核心執行測試時失敗，表示測試本身有誤，或是對 Linux 行為的假設有誤。您必須先修正測試，使其在 Linux 上通過，才能用來驗證 Starnix。

如要編寫新測試，請按照下列步驟操作：

開發測試並針對主機 Linux 核心執行。確認建構作業已設定為納入測試：
```
fx set workbench_eng.x64 \
    --with-test //src/starnix/tests/syscalls/cpp:tests
```
接著，在 Linux 主機上執行測試。主機測試目標名稱與目標測試名稱相同，但會加上 starnix_ 前置字元和 _host 後置字元。舉例來說，如要執行 hello_starnix_test：
```
fx test starnix_hello_starnix_test_host
```
注意： GN 的 syscall_test 範本會自動為每項測試建立 Linux 目標。這個 Linux 目標會指派與 Fuchsia 測試相同的目標名稱，但會加上 starnix_ 前置字元和 _host 後置字元。

反覆測試，直到主機 Linux 核心通過 100% 的測試為止。
以預期失敗的測試登陸。如果 Starnix 尚未完全實作系統呼叫，Starnix 測試目標就會失敗。您應使用測試期望值新增預期的失敗 (請參閱「使用測試期望值」)，並將測試套件做為基準，而非等待系統呼叫完成。
在 Starnix 中實作這項功能。在 Linux 上通過基準測試後，請開始在 Starnix 核心中實作系統呼叫。如需編寫 Starnix 系統呼叫的指引，請參閱「Starnix 系統呼叫評分標準」和「常見的編碼模式」。
針對 Starnix 執行測試。連線 Fuchsia 裝置或執行模擬器後，請執行測試：
```
fx test hello_starnix_test
```
反覆調整 Starnix 實作項目，直到測試通過為止。如果測試通過，請更新測試期望 (請參閱「使用測試期望」)，移除預期失敗。

使用測試期望

您在 Linux 主機上測試的部分系統呼叫可能尚未在 Starnix 中完全實作。如果測試在 Linux 上順利執行，但在 Starnix 上失敗，Fuchsia 建構作業就會變成紅色。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",
    ],
}

在 //src/starnix/tests/syscalls/cpp/BUILD.gn 中，將 "hello_starnix_test" 新增至 syscall_tests 清單：
```
syscall_tests = [
  # ... other tests ...
  "hello_starnix_test",
  # ...
]
```
建構更新後的測試套件：
```
fx build
```
執行新的測試 (須使用 Fuchsia 裝置或模擬器)：
```
fx test hello_starnix_test
```

由於 .json5 檔案中新增了預期結果，測試執行元件會預期測試在 Starnix 上失敗。建構作業會成功，且測試執行會回報為通過。在 Starnix 中實作缺少的系統呼叫後，即可從 .json5 檔案中移除預期。

後續步驟

進一步瞭解 Starnix 概念。
請參閱 Starnix 系統呼叫說明文件。
請參閱這篇文章，瞭解如何使用 Linux 二進位檔測試 Starnix。