撰寫及執行 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 和 Fuchsia 環境中，編譯及執行的測試二進位檔完全相同。這項測試可驗證您對 Linux 行為的瞭解程度，以及 Starnix 實作的準確度。

對 Linux 環境執行測試的方法有兩種：

Machina (建議使用)：在 Linux 虛擬機器中執行測試。建議採用這種做法，因為這會使用目標核心版本，提供標準化的獨立環境。不過，執行 Machina 需要以 Intel 為基礎的 CPU。如要進一步瞭解如何設定及使用 Machina，請參閱「Linux 測試的 Machina 執行階段」。
主體機器測試 (備援)：直接在 Linux 主體機器上執行測試。如果使用者沒有 Intel CPU，或是要進行簡單測試 (不依賴主機環境不支援的功能)，可以改用這個方法。請注意，您必須使用 GN 引數 starnix_force_build_host_tests = true 明確啟用主機測試建構作業。

如果針對 Linux 環境執行的測試失敗，可能表示測試本身有誤，或是對 Linux 行為的假設不正確。您應先修正測試，確保測試在 Linux 上通過，再使用測試驗證 Starnix。

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

開發測試並在 Linux 環境中執行。
- 偏好：使用 Machina (需要 Intel CPU)。請參閱「Machina Linux 測試執行階段」。
- 備用：執行主機測試。請確認建構作業已設定為納入測試，並強制建構主機測試：
```
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 系統呼叫評分量表」和「常見的程式設計模式」。
針對 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。