Adding `rstest` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add --dev rstest

to add it a dev dependency (if it's used only in tests, not in the final product). To add it as a regular run-time dependency, run:

cargo add rstest

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

rstest = "0.26.1"

The rstest library will be automatically available globally. Read the rstest library documentation.

Back to the crate overview.

Readme

Fixture-based test framework for Rust

Introduction

rstest uses procedural macros to help you on writing fixtures and table-based tests. To use it, add the following lines to your Cargo.toml file:

[dev-dependencies]
rstest = "0.26.1"

Features

async-timeout: timeout for async tests (Default enabled)
crate-name: Import rstest package with different name (Default enabled)

Fixture

The core idea is that you can inject your test dependencies by passing them as test arguments. In the following example, a fixture is 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);
}

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 will generate an independent test for each case.

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 in 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 ... 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)] argument attribute:

use rstest::rstest;

#[rstest]
fn should_be_invalid(
    #[values(None, Some(""), Some("    "))]
    value: Option<&str>
) {
    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 crate. With this helper crate you can define a template and use it everywhere.

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 for more details.

Feature flagged cases

In case you want certain test cases to only be present if a certain feature is enabled, use #[cfg_attr(feature = …, case(…))]:

use rstest::rstest;

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

This also works with rstest_reuse.

Magic Conversion

If you need a value where its type implement FromStr() trait you can use a literal string to build it:

# 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 supports async tests, but makes no assumptions about what async runtime you are using. Async tests require either an explicit test attribute or an implicit test attribute.

You are responsible for providing any appropriate peer dependencies to run your async tests.

If your test input is an async value (fixture or test parameter) you can use #[future] attribute to remove impl Future<Output = T> boilerplate and just use T:

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

#[rstest]
#[tokio::test]
#[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);
}

As you noted you should .await all future values and this sometimes can be really boring. In this case you can use #[future(awt)] to awaiting an input or annotating your function with #[awt] attributes to globally .await all your future inputs. Previous code can be simplified as follows:

use rstest::*;
# #[fixture]
# async fn base() -> u32 { 42 }
#[rstest]
#[tokio::test]
#[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]
#[tokio::test]
#[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 path as input arguments

If you need to create a test for each file in a given location you can use #[files("glob path syntax")] attribute to generate a test for each file that satisfy the given glob path.

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

The default behavior is to ignore the files that start with ".", but you can modify this by use #[include_dot_files] attribute. The files attribute can be used more than once on the same variable, and you can also create some custom exclusion rules with the #[exclude("regex")] attributes that filter out all paths that verify the regular expression.

You can pass in environment variables by using ${ENV_VAR_NAME} in the glob path, e.g. #[files("${SOME_ENV}/hello")]. To set a default value for the environment variable, use ${ENV_VAR_NAME:-default_value}.

Files are resolved at compile time against your Cargo project root (the CARGO_MANIFEST_DIR environment variable). If you need to change this behavior, you can use the #[base_dir = "..."] attribute to specify a different base directory. That directory MUST exist, and will be used as the root for the files, as well as to resolve the relative path when creating the test name. Similar to the files attribute, you can use ${ENV_VAR_NAME} in the base_dir.

The #[files(...)] attribute ignores matched directory paths by default, returning only file paths. If you need the test cases to include directories found by the glob pattern, use the #[dirs] attribute in conjunction with #[files(...)].

Use `#[once]` Fixture

If you need to a fixture that should be initialized just once for all tests you can use #[once] attribute. rstest call your fixture function just once and return a reference to your function result to all your tests:

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

#[rstest]
fn single(once_fixture: &i32) {
    // All tests that use once_fixture will share the same reference to once_fixture()
    // function result.
    assert_eq!(&42, once_fixture)
}

Test `#[timeout()]`

You can define an execution timeout for your tests with #[timeout(<duration>)] attribute. Timeout works both for sync and async tests and is runtime agnostic. #[timeout(<duration>)] take an expression that should return a std::time::Duration. Follow a simple async example:

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]
#[async_std::test]
#[timeout(Duration::from_millis(80))]
async fn single_pass() {
    assert_eq!(4, delayed_sum(2, 2, ms(10)).await);
}

In this case test pass because the delay is just 10 milliseconds and timeout is 80 milliseconds.

You can use timeout attribute like any other attribute in your tests, and you can override a group timeout with a case specific one. In the follow example we have 3 tests where first and third use 100 milliseconds but the second one use 10 milliseconds. Another valuable point in this example is to use an expression to compute the duration.

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

If you want to use timeout for async test you need to use async-timeout feature (enabled by default).

Default timeout

You can set a default timeout for test using the RSTEST_TIMEOUT environment variable. The value is in seconds and is evaluated on test compile time.

Explicit Test Attribute

If your test contains an attribute #[test_attr(...)], this is an explicit test attribute declaration. The contents of the parentheses will be inserted as an attribute of your test. This allows for arbitrary test attribute syntax.

For instance, if you want to test an async function with smol_macros::test, you can write

use rstest::*;
use macro_rules_attribute::apply;
use smol_macros::test;
use std::future::Future;

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

When using an explicit test attribute, ensure it appears after any #[case()] attributes so that the attribute binds to the test function and not the case.

Implicit Test Attribute

If your test contains an attribute whose path ends in test, this is treated as an implicit test attribute, and replaces the default #[test] attribute. Simply including the attribute in your test's attribute list is all that is required.

For instance, if you want to test an async function with the actix_rt::test attribute, you can just write:

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

Implicit test attributes have a lower priority than explicit test attributes. If you have an unrelated attribute whose path ends in test, you should declare an explicit test attribute for deconfliction.

When using an implicit test attribute, ensure it appears after any #[case()] attributes so that the attribute binds to the test function and not the case.

Default Test Attribute

Synchronous tests use #[test] as the default test attribute if nothing else is supplied explicitly or implicitly.

Asynchronous tests will fail to compile if no test attribute is specified explicitly or implicitly.

Test `Context` object

You can have a Context object for your test just by annotate an argument by #[context] attribute. This object contains some useful information both to implement simple logics and debugging stuff.

use rstest::{rstest, Context};

#[rstest]
#[case::a_description(42)]
fn my_test(#[context] ctx: Context, #[case] _c: u32) {
    assert_eq!("my_test", ctx.name);
    assert_eq!(Some("a_description"), ctx.description);
    assert_eq!(Some(0), ctx.case);

    std::thread::sleep(std::time::Duration::from_millis(100));
    assert!(ctx.start.elapsed() >= std::time::Duration::from_millis(100));
}

Local lifetime and `#[by_ref]` attribute

In some cases you may want to use a local lifetime for some arguments of your test. In these cases you can use the #[by_ref] attribute then use the reference instead the value.

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

You can use #[by_ref] attribute for all arguments of your test and not just for fixture but also for cases, values and files.

Complete Example

All these features can be used together with a mixture of fixture variables, fixed cases and a 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::authorized_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 `authorized_user`
#[should_panic(expected = "Invalid query error")] // We would test a 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();
}

This example will generate exactly 6 tests grouped by 2 different cases:

running 6 tests
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

test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Note that the names of the values try to convert the input expression in a Rust valid identifier name to help you find which tests fail.

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 attribute to your test to enable the dump of all input variables.

#[rstest]
#[case(42, "FortyTwo", ("minus twelve", -12))]
#[case(24, "TwentyFour", ("minus twentyfour", -24))]
#[trace] //This attribute enable tracing
fn should_fail(#[case] number: u32, #[case] name: &str, #[case] tuple: (&str, i32)) {
    assert!(false); // <- stdout come out just for failed tests
}

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.

Adding rstest library as a dependency

Adding `rstest` library as a dependency