测试 Rust 代码

本文档介绍了为 Rust 代码编写测试的最佳实践。如需了解如何定义测试软件包和组件以及运行它们,请参阅组件测试指南

本文档面向在 fuchsia.git 中工作的开发者,其中所述的工作流不太适用于 IDK 使用方。

本教程的源代码位于 //examples/hello_world/rust

单元测试

向代码添加测试

添加 Rust 单元测试的惯用方法在 Fuchsia 内外都适用,只需将以下代码段放入要编写的任何测试的底部,即可轻松实现:

#[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_binaryrustc_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 会导致此 build 规则生成两个不同的可执行文件,一个使用提供的名称,另一个在提供的名称后附加 _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! 宏,用于在断言失败时显示彩色差异。

这些内容可添加到 BUILD.gntest_deps 下。

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",
  ]
}