Fixture-based test framework for Rust
rstestuses procedural macros to help you on writing fixtures and table-based tests. To use it, add the following lines to your
Cargo.tomlfile:
[dev-dependencies] rstest = "0.6.5"
The core idea is that you can inject your test dependencies by passing them as test arguments. In the following example, a
fixtureis defined and then used in two tests, simply providing it as an argument:
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); }
You can also inject values in some other ways. For instance, you can create a set of tests by simply providing the injected values for each case:
rstestwill generate an independent test for each case.
use rstest::rstest;#[rstest(input, expected, case(0, 0), case(1, 1), case(2, 1), case(3, 2), case(4, 3) )] fn fibonacci_test(input: u32, expected: u32) { assert_eq!(expected, fibonacci(input)) }
Running
cargo testin this case executes five tests:
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 ... oktest result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
If you need to just providing a bunch of values for which you need to run your test, you can use
var => [list, of, values]syntax:
use rstest::rstest;#[rstest( value => [None, Some(""), Some(" ")] )] fn should_be_invalid(value: Option) { assert!(!valid(value)) }
Or create a matrix test by using list of values for some variables that will generate the cartesian product of all the values.
If you need to use a test list for more than one test you can use
rstest_reusecrate. With this helper crate you can define a template and use it everywhere .
use rstest::rstest; use rstest_reuse::{self, *};#[template] #[rstest(a, b, case(2, 2), case(4/2, 2), ) ] fn two_simple_cases(a: u32, b: u32) {}
#[apply(two_simple_cases)] fn it_works(a: u32, b: u32) { assert!(a == b); }
rstest_reusefor more dettails.
rstestprovides out of the box
asyncsupport. Just mark your test function as
asyncand it'll use
#[async-std::test]to annotate it. This feature can be really useful to build async parametric tests using a tidy syntax:
use rstest::*;#[rstest(expected, a, b, case(5, 2, 3), #[should_panic] case(42, 40, 1) )] async fn my_async_test(expected: u32, a: u32, b: u32) { assert_eq!(expected, async_sum(a, b).await); }
Currently only
async-stdis supported out of the box. But if you need to use another runtime that provide it's own test attribute (i.e.
tokio::testor
actix_rt::test) you can use it in your
asynctest like described in Inject Test Attribute.
To use this feature, you need to enable
attributesin the
async-stdfeatures list in your
Cargo.toml:
async-std = { version = "1.5", features = ["attributes"] }
If you would like to use another
testattribute for your test you can simply indicate it in your test function's attributes. For instance if you want to test some async function with use
actix_rt::testattribute you can just write:
use rstest::*; use actix_rt; use std::future::Future;#[rstest(a, result, case(2, async { 4 }), case(21, async { 42 }) )] #[actix_rt::test] async fn my_async_test(a: u32, result: impl Future) { assert_eq!(2 * a, result.await); }
Just the attributes that ends with
test(last path segment) can be injected.
All these features can be used together with a mixture of fixture variables, fixed cases and bunch of values. For instance, you might need two test cases which test for panics, one for a logged in user and one for a guest user.
use rstest::*;#[fixture] fn repository() -> InMemoryRepository { let mut r = InMemoryRepository::default(); // fill repository with some data r }
#[fixture] fn alice() -> User { User::logged("Alice", "2001-10-04", "London", "UK") }
#[rstest(user, case::authed_user(alice()), // We can use
fixture
also as standard function case::guest(User::Guest), // We can give a name to every case :guest
in this case // andauthed_user
query => [" ", "^%$#@!", "...." ] )] #[should_panic(expected = "Invalid query error")] // We whould test a panic fn should_be_invalid_query_error(repository: impl Repository, user: User, query: &str) { repository.find_items(&user, query).unwrap(); }
This example will generate exactly 6 tests grouped by 2 different cases:
running 6 tests test should_be_invalid_query_error::case_1_authed_user::query_1 ... ok test should_be_invalid_query_error::case_2_guest::query_2 ... ok test should_be_invalid_query_error::case_2_guest::query_3 ... ok test should_be_invalid_query_error::case_1_authed_user::query_2 ... ok test should_be_invalid_query_error::case_1_authed_user::query_3 ... ok test should_be_invalid_query_error::case_2_guest::query_1 ... oktest result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
Is that all? Not quite yet!
A fixture can be injected by another fixture and they can be called using just some of its arguments.
#[fixture(name="Alice", age=22)] fn user(name: &str, 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(user("Bob"))] fn is_bob(user: User) { assert_eq!(user.name(), "Bob") }
#[rstest(user("", 42))] fn is_42(user: User) { assert_eq!(user.age(), 42) }
As you noted you can provide default values without the need of a fixture to define it.
Finally if you need tracing the input values you can just add the
traceattribute to your test to enable the dump of all input variables.
#[rstest( number, name, tuple, case(42, "FortyTwo", ("minus twelve", -12)), case(24, "TwentyFour", ("minus twentyfour", -24)) ::trace //This attribute enable traceing )] fn should_fail(number: u32, name: &str, tuple: (&str, i32)) { assert!(false); //running 2 tests test should_fail::case_1 ... FAILED test should_fail::case_2 ... FAILEDfailures:
---- should_fail::case_1 stdout ---- ------------ TEST ARGUMENTS ------------ number = 42 name = "FortyTwo" tuple = ("minus twelve", -12) -------------- TEST START -------------- thread 'should_fail::case_1' panicked at 'assertion failed: false', src/main.rs:64:5 note: run with
RUST_BACKTRACE=1
environment variable to display a backtrace.---- should_fail::case_2 stdout ---- ------------ TEST ARGUMENTS ------------ number = 24 name = "TwentyFour" tuple = ("minus twentyfour", -24) -------------- TEST START -------------- thread 'should_fail::case_2' panicked at 'assertion failed: false', src/main.rs:64:5
failures: should_fail::case_1 should_fail::case_2
test result: FAILED. 0 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out
In case one or more variables don't implement the
Debugtrait, an error is raised, but it's also possible to exclude a variable using thenotrace(var,list,that,not,implement,Debug)attribute.You can learn more on Docs and find more examples in
resourcesdirectory and inrs8080which uses this module in-depth.Changelog
See CHANGELOG.md
License
Licensed under either of
Apache License, Version 2.0, (LICENSE-APACHE or license-apache-link)
MIT license LICENSE-MIT or license-MIT-link at your option.