Crate Docs Status Apache 2.0 Licensed MIT Licensed Rust 1.32+

Fixture-based test framework for Rust

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.5"

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 indicating it as argument:

```rust use rstest::*;

[fixture]

pub fn fixture() -> u32 { 42 }

[rstest]

fn shouldsuccess(fixture: u32) {     asserteq!(fixture, 42); }

[rstest]

fn shouldfail(fixture: u32) {     assertne!(fixture, 42); } ```

You can also inject values in some other ways. For instance, you can create a set of tests by simply indicating the injected values for each case: rstest will generate an independent test for each case.

```rust use rstest::rstest;

[rstest(input, expected,

case(0, 0),
case(1, 1),
case(2, 1),
case(3, 2),
case(4, 3)

)] fn fibonaccitest(input: u32, expected: u32) { asserteq!(expected, fibonacci(input)) } ```

Running cargo test in this case executes five tests:

```bash running 5 tests test fibonaccitest::case1 ... ok test fibonaccitest::case2 ... ok test fibonaccitest::case3 ... ok test fibonaccitest::case4 ... ok test fibonaccitest::case5 ... ok

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

If you need to just indicate a bunch of values for which you need to run your test you can use var => [list, of, values] syntax:

```rust use rstest::rstest;

[rstest(

value => [None, Some(""), Some("    ")]

)] fn shouldbeinvalid(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.

All these features can be used together with mix fixture variables, fixed cases and bunch of values. For instance you need two tests that given your repository in cases of both logged in or guest user should return an invalid query error.

```rust use rstest::*;

[fixture]

fn repository() -> InMemoryRepository { let mut r = InMemoryRepository::default(); // fill repository by some data r }

[fixture]

fn alice() -> User { User::logged("Alice", "2001-10-04", "London", "UK") }

[rstest(user,

case::logged_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
query => ["     ", "^%$#@!", "...." ]

)]

[should_panic(expected = "Invalid query error")] // We whould test a panic

fn shouldbeinvalidqueryerror(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 shouldbeinvalidqueryerror::case1loggeduser::query1 ... ok test shouldbeinvalidqueryerror::case2guest::query2 ... ok test shouldbeinvalidqueryerror::case2guest::query3 ... ok test shouldbeinvalidqueryerror::case1loggeduser::query2 ... ok test shouldbeinvalidqueryerror::case1loggeduser::query3 ... ok test shouldbeinvalidqueryerror::case2guest::query_1 ... ok

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

Is that all? Not yet!

A fixture can be injected by another fixture and they can be called using just some of its arguments.

```rust

[fixture]

fn name() -> &'static str { "Alice" }

[fixture]

fn age() -> u8 { 22 }

[fixture]

fn user(name: &str, age: u8) -> User { User::new(name, age) }

[rstest]

fn isalice(user: User) { asserteq!(user.name(), "Alice") }

[rstest]

fn is22(user: User) { asserteq!(user.age(), 22) }

[rstest(user("Bob"))]

fn isbob(user: User) { asserteq!(user.name(), "Bob") }

[rstest(user("", 42))]

fn is42(user: User) { asserteq!(user.age(), 42) } ```

Currently, using a fixture is required also to just provide default value, but this will change soon with the introduction of a syntax for default values, without the need of the fixture function definition.

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.

```rust

[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); // <- stdout come out just for failed tests } ```

``` running 2 tests test shouldfail::case1 ... FAILED test shouldfail::case2 ... FAILED

failures:

---- shouldfail::case1 stdout ---- ------------ TEST ARGUMENTS ------------ number = 42 name = "FortyTwo" tuple = ("minus twelve", -12) -------------- TEST START -------------- thread 'shouldfail::case1' panicked at 'assertion failed: false', src/main.rs:64:5 note: run with RUST_BACKTRACE=1 environment variable to display a backtrace.

---- shouldfail::case2 stdout ---- ------------ TEST ARGUMENTS ------------ number = 24 name = "TwentyFour" tuple = ("minus twentyfour", -24) -------------- TEST START -------------- thread 'shouldfail::case2' panicked at 'assertion failed: false', src/main.rs:64:5

failures: shouldfail::case1 shouldfail::case2

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(var,list,that,not,implement,Debug) attribute.

You can learn more on Docs and find more examples in resources directory and in rs8080 which uses this module in-depth.

Changelog

See CHANGELOG.md

License

Licensed under either of