Logo
Project Icon

rstest

Rust测试框架 基于fixture的灵活测试工具

Rust测试框架fixture参数化测试异步测试Github开源项目

rstest是一款基于fixture的Rust测试框架,通过过程宏简化测试编写。它支持依赖注入、参数化测试、异步测试、超时设置和文件路径输入等功能,使Rust测试更加灵活高效。rstest适用于复杂测试场景,支持多种运行时,并提供丰富配置选项,可满足各类项目需求。该框架简化了测试流程,提高了测试效率和可维护性。

访问官网访问官网GithubGithub文档文档论文论文
介绍相关项目

[![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

如果一个或多个变量没有实现 Debug trait,则会引发错误,但也可以使用 #[notrace] 参数属性排除某个变量。

你可以在 [文档][docs-link] 中了解更多信息,并在 tests/resources 目录中找到更多示例。

Rust 版本兼容性

支持的最低 Rust 版本是 1.67.1。

变更日志

请参阅 CHANGELOG.md

许可证

根据以下两种许可证之一进行许可

  • Apache License, Version 2.0, (LICENSE-APACHE 或 [license-apache-link])

  • MIT license LICENSE-MIT 或 [license-MIT-link] 由你选择。

相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具，简化了选题、文献检索至论文撰写的整个过程。通过简单设定，平台可快速生成高质量论文大纲和全文，配合图表、参考文献等一应俱全，同时提供开题报告和答辩PPT等增值服务，保障数据安全，有效提升写作效率和论文质量。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号