測試 Rust 程式碼

本文說明為 Rust 程式碼編寫測試的最佳做法。如需定義測試套件和元件並執行的操作說明，請參閱元件測試指南。

這份文件的對象是 fuchsia.git 內部的開發人員，因此本文所述的工作流程不太可能適用於 IDK 使用者。

您可以在 //examples/hello_world/rust 中取得本教學課程的原始碼。

單元測試

在程式碼中新增測試

在 Fuchsia 內部和外部，Rust 單元測試的慣用新增方式都同樣有效，只要將下列程式碼片段放到您要編寫的任何測試底部，即可輕鬆完成：

#[cfg(test)]
mod tests {
    #[fuchsia::test]
    fn it_works() {
        assert_eq!(true, true);
    }
}

這會導致系統建立名為 tests 的新模組，且這個模組只會在建構單元測試時納入。任何加上 #[fuchsia::test] 註解的函式都會做為測試執行，如果函式成功傳回，則測試會通過。

#[fuchsia::test] 也支援測試非同步程式碼。

#[fuchsia::test]
async fn my_test() {
    let some_future = async { 4 };
    assert_eq!(some_future.await, 4);
}

一般 #[test] 註解也適用，但不支援非同步測試或記錄。如果您認為 Crate 可能會用於 Fuchsia 程式碼集之外，請優先使用 #[test]。

建構測試

單元測試可由 Rust 目標 (即 rustc_binary 或 rustc_library) 自動建構。兩種方法大致相同。

為 Rust 二進位檔建構測試

如果您要測試 Rust 二進位檔 (也就是您有 main.rs)，這一節就很實用。如果您有程式庫，請參閱下一節。

BUILD.gn 檔案必須先匯入 rustc_binary 範本，才能提供該範本：

import("//build/rust/rustc_binary.gni")

只有在新增 with_unit_tests = true 設定時，單元測試才會由 rustc_binary GN 範本建構：

rustc_binary("bin") {
  name = "hello_world_rust"

  # Generates the "bin_test" build target
  with_unit_tests = true
  edition = "2021"

  deps = []
  test_deps = [ "//src/lib/fuchsia" ]

  sources = [ "src/main.rs" ]
}

設定 with_unit_tests = true 會導致這個建構規則產生兩個不同的可執行檔，一個使用提供的名稱，另一個則在提供的名稱後方加上 _bin_test。

在本範例中，建立的可執行檔名稱會稱為：

  • hello_world_rust；
  • hello_world_rust_bin_test。

為 Rust 程式庫建構測試

BUILD.gn 檔案必須先匯入 rustc_library 範本，才能提供該範本：

import("//build/rust/rustc_library.gni")

只有在新增 with_unit_tests = true 設定時，單元測試才會由 rustc_library GN 範本建構，這與上述 rustc_binary 的情況類似。

不過，在這種情況下，系統會建立名稱不同的測試二進位檔：

  • hello_world_rust_lib_test。請注意，二進位檔的名稱與程式庫產生的名稱不同。

二進位名稱很重要，因為後續步驟會用到這些名稱。

打包及執行測試

如要執行先前目標產生的測試，請將這些測試封裝為測試元件。測試元件包含 您可以使用下列建構規則套件測試：

  • fuchsia_test_package()：套件範本，可將多個測試元件及其依附元件收集到單一套件中。測試套件通常用於整合測試。
  • fuchsia_unittest_package()：專門適用於包含單元測試的套件。單元測試套件可為不具備必要功能的單元測試產生最小元件資訊清單。

以 Hello World 二進位檔為例，單元測試套件會參照產生的目標 bin_test (根據目標名稱 bin 和隱含後置字 _test) 和 hello_world_rust_bin_test (根據 name 節的值)。

fuchsia_unittest_package("hello-world-rust-tests") {
  deps = [ ":bin_test" ]
}

如要執行測試，請按照下列步驟操作：

fx test hello-world-rust-tests

如要進一步瞭解如何封裝及執行測試，請參閱「測試元件」和「建構元件」。

實用的 Crate

下列樹狀結構內第三方 Crate 可協助您編寫測試：

  • assert_matches：提供巨集 assert_matches!，讓模式斷言更符合人體工學。
  • pretty_assertions：提供替代 assert_eq! 巨集，在斷言失敗時顯示彩色差異。

您可以將這些值加入 test_deps 底下的 BUILD.gn。

rustc_binary("bin") {
  name = "my_test"
  with_unit_tests = true
  edition = "2021"

  test_deps = [
    "//third_party/rust_crates:matches",
    "//third_party/rust_crates:pretty_assertions",
  ]
}