Fixture-based test framework for Rust

Introduction

rstest

Cargo.toml

[dev-dependencies]
rstest = "0.12.0"

Fixture

The core idea is that you can inject your test dependencies by passing them as test arguments. In the following example, a

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);
}

Parametrize

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:

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))
}

Running

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

If you need to just providing a bunch of values for which you need to run your test, you can use

#[values(list, of, values)]

use rstest::rstest;

#[rstest]
fn should_be_invalid(
    #[values(None, Some(""), Some("    "))]
    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.

Use Parametrize definition in more tests

If you need to use a test list for more than one test you can use

rstest_reuse

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);
}

See

rstest_reuse

Magic Conversion

If you need a value where its type implement

FromStr()

# 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());
}

You can use this feature also in value list and in fixture default value.

Async

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);
}

Currently only

async-std

tokio::test

actix_rt::test

async

To use this feature, you need to enable

attributes

async-std

Cargo.toml

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

If your test input is an async value (fixture or test parameter) you can use

#[future]

impl Future

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);
}

Inject Test Attribute

If you would like to use another

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, result: #[case] #[future] u32) {
    assert_eq!(2 * a, result.await);
}

Just the attributes that ends with

test

Complete Example

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]
#[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
                              // and authed_user
#[should_panic(expected = "Invalid query error")] // We whould test a panic
fn should_be_invalid_query_error(
    repository: impl Repository, 
    #[case] user: User, 
    #[values("     ", "^%$#@!", "....")]
    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 ... ok

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

More

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]
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)
}

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

trace

#[rstest]
#[case(42, "FortyTwo", ("minus twelve", -12))]
#[case(24, "TwentyFour", ("minus twentyfour", -24))]
#[trace] //This attribute enable traceing
fn should_fail(#[case] number: u32, #[case] name: &str, #[case] tuple: (&str, i32)) {
    assert!(false); // 
running 2 tests
test should_fail::case_1 ... FAILED
test should_fail::case_2 ... FAILED

failures:
---- 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 
Debug
 trait, an error
is raised, but it's also possible to exclude a variable using the
#[notrace]
 argument attribute.

You can learn more on Docs and find more examples in 
tests/resources
 directory.


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.