[![Crate][crate-image]][crate-link] [![文档][docs-image]][docs-link] [![状态][test-action-image]][test-action-link] [![Apache 2.0 许可证][license-apache-image]][license-apache-link] [![MIT 许可证][license-mit-image]][license-mit-link]

Rust 的基于固件的测试框架

简介

rstest 使用过程宏来帮助您编写固件和基于表格的测试。要使用它，请在您的 Cargo.toml 文件中添加以下行：

[dev-dependencies]
rstest = "0.22.0"

特性

async-timeout：用于 async 测试的 timeout（默认启用）
crate-name：以不同名称导入 rstest 包（默认启用）

固件

核心思想是您可以通过将测试依赖项作为测试参数传递来注入它们。在以下示例中，定义了一个 fixture，然后在两个测试中使用，只需将其作为参数提供：

use rstest::*;

#[fixture]
pub fn fixture() -> u32 { 42 }

#[rstest]
fn should_success(fixture: u32) {
    assert_eq!(fixture, 42);
}

#[rstest]
fn should_fail(fixture: u32) {
    assert_ne!(fixture, 42);
}

参数化

您还可以通过其他方式注入值。例如，您可以通过简单地为每个案例提供注入的值来创建一组测试：rstest 将为每个案例生成一个独立的测试。

use rstest::rstest;

#[rstest]
#[case(0, 0)]
#[case(1, 1)]
#[case(2, 1)]
#[case(3, 2)]
#[case(4, 3)]
fn fibonacci_test(#[case] input: u32, #[case] expected: u32) {
    assert_eq!(expected, fibonacci(input))
}

在这种情况下运行 cargo test 将执行五个测试：

running 5 tests
test fibonacci_test::case_1 ... ok
test fibonacci_test::case_2 ... ok
test fibonacci_test::case_3 ... ok
test fibonacci_test::case_4 ... ok
test fibonacci_test::case_5 ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

如果您只需要提供一组需要运行测试的值，可以使用 #[values(值, 列表)] 参数属性：

use rstest::rstest;

#[rstest]
fn should_be_invalid(
    #[values(None, Some(""), Some("    "))]
    value: Option<&str>
) {
    assert!(!valid(value))
}

或者通过为某些变量使用 值列表 来创建矩阵测试，这将生成所有值的笛卡尔积。

在多个测试中使用参数化定义

如果您需要在多个测试中使用测试列表，可以使用 [rstest_reuse][reuse-crate-link] crate。使用这个辅助 crate，您可以定义一个模板并在任何地方使用它。

use rstest::rstest;
use rstest_reuse::{self, *};

#[template]
#[rstest]
#[case(2, 2)]
#[case(4/2, 2)]
fn two_simple_cases(#[case] a: u32, #[case] b: u32) {}

#[apply(two_simple_cases)]
fn it_works(#[case] a: u32, #[case] b: u32) {
    assert!(a == b);
}

有关更多详细信息，请参阅 [rstest_reuse][reuse-crate-link]。

特性标记的案例

如果您希望某些测试案例仅在启用特定特性时存在，请使用 #[cfg_attr(feature = …, case(…))]：

use rstest::rstest;

#[rstest]
#[case(2, 2)]
#[cfg_attr(feature = "frac", case(4/2, 2))]
#[case(4/2, 2)]
fn it_works(#[case] a: u32, #[case] b: u32) {
    assert!(a == b);
}

这也适用于 [rstest_reuse][reuse-crate-link]。

魔法转换

如果您需要一个其类型实现了 FromStr() trait 的值，您可以使用字面字符串来构建它：

# use rstest::rstest;
# use std::net::SocketAddr;
#[rstest]
#[case("1.2.3.4:8080", 8080)]
#[case("127.0.0.1:9000", 9000)]
fn check_port(#[case] addr: SocketAddr, #[case] expected: u16) {
    assert_eq!(expected, addr.port());
}

您也可以在值列表和固件默认值中使用此功能。

异步

rstest 提供开箱即用的 async 支持。只需将您的测试函数标记为 async，它就会使用 #[async-std::test] 来注解它。这个功能在使用简洁的语法构建异步参数化测试时非常有用：

use rstest::*;

#[rstest]
#[case(5, 2, 3)]
#[should_panic]
#[case(42, 40, 1)]
async fn my_async_test(#[case] expected: u32, #[case] a: u32, #[case] b: u32) {
    assert_eq!(expected, async_sum(a, b).await);
}

目前，开箱即用只支持 async-std。但如果您需要使用提供自己测试属性的其他运行时（例如 tokio::test 或 actix_rt::test），您可以按照注入测试属性中描述的方式在 async 测试中使用它。

要使用此功能，您需要在 Cargo.toml 中的 async-std 特性列表中启用 attributes：

async-std = { version = "1.5", features = ["attributes"] }

如果您的测试输入是一个异步值（固件或测试参数），您可以使用 #[future] 属性来移除 impl Future<Output = T> 样板代码，直接使用 T：

use rstest::*;
#[fixture]
async fn base() -> u32 { 42 }

#[rstest]
#[case(21, async { 2 })]
#[case(6, async { 7 })]
async fn my_async_test(#[future] base: u32, #[case] expected: u32, #[future] #[case] div: u32) {
    assert_eq!(expected, base.await / div.await);
}

正如您所注意到的，您应该对所有 future 值使用 .await，这有时可能会非常繁琐。在这种情况下，您可以使用 #[future(awt)] 来 awaiting 一个输入，或者用 #[awt] 属性注解您的函数，以全局对所有 future 输入使用 .await。之前的代码可以简化如下：

use rstest::*;
# #[fixture]
# async fn base() -> u32 { 42 }
#[rstest]
#[case(21, async { 2 })]
#[case(6, async { 7 })]
#[awt]
async fn global(#[future] base: u32, #[case] expected: u32, #[future] #[case] div: u32) {
    assert_eq!(expected, base / div);
}
#[rstest]
#[case(21, async { 2 })]
#[case(6, async { 7 })]
async fn single(#[future] base: u32, #[case] expected: u32, #[future(awt)] #[case] div: u32) {
    assert_eq!(expected, base.await / div);
}

文件路径作为输入参数

如果您需要为给定位置的每个文件创建测试，可以使用 #[files("glob 路径语法")] 属性为满足给定 glob 路径的每个文件生成一个测试。

#[rstest]
fn for_each_file(#[files("src/**/*.rs")] #[exclude("test")] path: PathBuf) {
    assert!(check_file(&path))
}

默认行为是忽略以 "." 开头的文件，但您可以通过使用 #[include_dot_files] 属性来修改这一点。files 属性可以在同一变量上多次使用，您还可以使用 #[exclude("regex")] 属性创建一些自定义排除规则，以过滤掉所有符合正则表达式的路径。

默认超时

您可以使用 RSTEST_TIMEOUT 环境变量为测试设置默认超时。该值以秒为单位，在测试编译时进行评估。

测试 `#[timeout()]`

您可以使用 #[timeout(<duration>)] 属性为测试定义执行超时。超时适用于同步和异步测试，且与运行时无关。#[timeout(<duration>)] 接受一个应返回 std::time::Duration 的表达式。以下是一个简单的异步示例：

use rstest::*;
use std::time::Duration;

async fn delayed_sum(a: u32, b: u32,delay: Duration) -> u32 {
    async_std::task::sleep(delay).await;
    a + b
}

#[rstest]
#[timeout(Duration::from_millis(80))]
async fn single_pass() {
    assert_eq!(4, delayed_sum(2, 2, ms(10)).await);
}

在这种情况下，测试通过是因为延迟只有 10 毫秒，而超时设置为 80 毫秒。

您可以像在测试中使用其他属性一样使用 timeout 属性，并且可以用特定情况的超时覆盖组超时。在以下示例中，我们有 3 个测试，其中第一个和第三个使用 100 毫秒，但第二个使用 10 毫秒。这个示例的另一个值得注意的点是使用表达式来计算持续时间。

fn ms(ms: u32) -> Duration {
    Duration::from_millis(ms.into())
}

#[rstest]
#[case::pass(ms(1), 4)]
#[timeout(ms(10))]
#[case::fail_timeout(ms(60), 4)]
#[case::fail_value(ms(1), 5)]
#[timeout(ms(100))]
async fn group_one_timeout_override(#[case] delay: Duration, #[case] expected: u32) {
    assert_eq!(expected, delayed_sum(2, 2, delay).await);
}

如果您想为 async 测试使用 timeout，需要启用 async-timeout 特性（默认启用）。

注入测试属性

如果您想为测试使用另一个 test 属性，只需在测试函数的属性中指明即可。例如，如果您想使用 actix_rt::test 属性测试一些异步函数，可以这样写：

use rstest::*;
use actix_rt;
use std::future::Future;

#[rstest]
#[case(2, async { 4 })]
#[case(21, async { 42 })]
#[actix_rt::test]
async fn my_async_test(#[case] a: u32, #[case] #[future] result: u32) {
    assert_eq!(2 * a, result.await);
}

只有以 test 结尾的属性（最后一个路径段）可以被注入。

使用 `#[once]` 夹具

如果您需要一个只为所有测试初始化一次的夹具，可以使用 #[once] 属性。rstest 只调用一次您的夹具函数，并为所有测试返回函数结果的引用：

#[fixture]
#[once]
fn once_fixture() -> i32 { 42 }

#[rstest]
fn single(once_fixture: &i32) {
    // 所有使用 once_fixture 的测试将共享同一个 once_fixture() 函数结果的引用。
    assert_eq!(&42, once_fixture)
}

局部生命周期和 `#[by_ref]` 属性

在某些情况下，您可能想为测试的某些参数使用局部生命周期。在这些情况下，您可以使用 #[by_ref] 属性，然后使用引用而不是值。

enum E<'a> {
    A(bool),
    B(&'a Cell<E<'a>>),
}

fn make_e_from_bool<'a>(_bump: &'a (), b: bool) -> E<'a> {
    E::A(b)
}

#[fixture]
fn bump() -> () {}
 
#[rstest]
#[case(true, E::A(true))]
fn it_works<'a>(#[by_ref] bump: &'a (), #[case] b: bool, #[case] expected: E<'a>) {
    let actual = make_e_from_bool(&bump, b);
    assert_eq!(actual, expected);
}

您可以对测试的所有参数使用 #[by_ref] 属性，不仅适用于夹具，也适用于案例、值和文件。

完整示例

所有这些特性可以结合使用，混合夹具变量、固定案例和一系列值。例如，您可能需要两个测试崩溃的测试用例，一个用于已登录用户，一个用于访客用户。

use rstest::*;

#[fixture]
fn repository() -> InMemoryRepository {
    let mut r = InMemoryRepository::default();
    // 用一些数据填充存储库
    r
}

#[fixture]
fn alice() -> User {
    User::logged("Alice", "2001-10-04", "London", "UK")
}
```rust
#[rstest]
#[case::authorized_user(alice())] // 我们也可以将 `fixture` 作为标准函数使用
#[case::guest(User::Guest)]   // 我们可以为每个用例命名:这里是 `guest` 
                              // 和 `authorized_user`
#[should_panic(expected = "Invalid query error")] // 我们将测试一个panic
fn should_be_invalid_query_error(
    repository: impl Repository,
    #[case] user: User,
    #[values("     ", "^%$some#@invalid!chars", ".n.o.d.o.t.s.")] query: &str,
) {
    repository.find_items(&user, query).unwrap();
}

这个例子将精确生成6个测试,分为2个不同的用例:

运行 6 个测试
test should_be_invalid_query_error::case_1_authorized_user::query_1_____ - should panic ... ok
test should_be_invalid_query_error::case_2_guest::query_2_____someinvalid_chars__ - should panic ... ok
test should_be_invalid_query_error::case_1_authorized_user::query_2_____someinvalid_chars__ - should panic ... ok
test should_be_invalid_query_error::case_2_guest::query_3____n_o_d_o_t_s___ - should panic ... ok
test should_be_invalid_query_error::case_1_authorized_user::query_3____n_o_d_o_t_s___ - should panic ... ok
test should_be_invalid_query_error::case_2_guest::query_1_____ - should panic ... ok

测试结果: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; 在 0.00s 内完成

注意,值的名称会_尝试_将输入表达式转换为有效的 Rust 标识符名称,以帮助你找出哪些测试失败。

这就是全部了吗?还没有!

一个fixture可以被另一个fixture注入,它们可以只使用部分参数调用。

#[fixture]
fn user(#[default("Alice")] name: &str, #[default(22)] age: u8) -> User {
    User::new(name, age)
}

#[rstest]
fn is_alice(user: User) {
    assert_eq!(user.name(), "Alice")
}

#[rstest]
fn is_22(user: User) {
    assert_eq!(user.age(), 22)
}

#[rstest]
fn is_bob(#[with("Bob")] user: User) {
    assert_eq!(user.name(), "Bob")
}

#[rstest]
fn is_42(#[with("", 42)] user: User) {
    assert_eq!(user.age(), 42)
}

如你所见,你可以提供默认值,而无需定义fixture。

最后,如果你需要跟踪输入值,只需在测试中添加 trace 属性即可启用所有输入变量的输出。

#[rstest]
#[case(42, "FortyTwo", ("minus twelve", -12))]
#[case(24, "TwentyFour", ("minus twentyfour", -24))]
#[trace] //此属性启用跟踪
fn should_fail(#[case] number: u32, #[case] name: &str, #[case] tuple: (&str, i32)) {
    assert!(false); // <- stdout 仅在测试失败时输出
}

运行 2 个测试
test should_fail::case_1 ... FAILED
test should_fail::case_2 ... FAILED

失败:

---- should_fail::case_1 stdout ----
------------ 测试参数 ------------
number = 42
name = "FortyTwo"
tuple = ("minus twelve", -12)
-------------- 测试开始 --------------
线程 'should_fail::case_1' 在 src/main.rs:64:5 处发生 panic: assertion failed: false
注意: 运行时添加 `RUST_BACKTRACE=1` 环境变量以显示回溯。

---- should_fail::case_2 stdout ----
------------ 测试参数 ------------
number = 24
name = "TwentyFour"
tuple = ("minus twentyfour", -24)
-------------- 测试开始 --------------
线程 'should_fail::case_2' 在 src/main.rs:64:5 处发生 panic: assertion failed: false


失败:
    should_fail::case_1
    should_fail::case_2

测试结果: FAILED. 0 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out