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.6.2"
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:
```rust use rstest::*;
pub fn fixture() -> u32 { 42 }
fn shouldsuccess(fixture: u32) { asserteq!(fixture, 42); }
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 providing the injected values for each
case: rstest will generate an independent test for each case.
```rust use rstest::rstest;
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 providing a bunch of values for which you
need to run your test, you can use var => [list, of, values]
syntax:
```rust use 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.
rstest provides out of the box async support. Just mark your
test function as async and it'll use #[async-std::test] to
annotate it. This feature can be really useful to build async
parametric tests using a tidy syntax:
```rust use rstest::*;
case(5, 2, 3),
#[should_panic]
case(42, 40, 1)
)] async fn myasynctest(expected: u32, a: u32, b: u32) { asserteq!(expected, asyncsum(a, b).await); } ```
Currently, you cannot write async #[fixture] and only async-std is
supported out of the box. But if you need to use another runtime
that provide it's own test attribute (i.e. tokio::test or actix_rt::test)
you can use it in your async test like described in Inject Test Attribute.
To use this feature, you need to enable attributes in the async-std
features list in your Cargo.toml:
toml
async-std = { version = "1.5", features = ["attributes"] }
If you would like to use another test attribute 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::test attribute you can just write:
```rust use rstest::*; use actix_rt; use std::future::Future;
case(2, async { 4 }),
case(21, async { 42 })
)]
async fn myasynctest(a: u32, result: impl Future
Just the attributes that ends withtest` (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.
```rust use rstest::*;
fn repository() -> InMemoryRepository { let mut r = InMemoryRepository::default(); // fill repository with some data r }
fn alice() -> User { User::logged("Alice", "2001-10-04", "London", "UK") }
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`
query => [" ", "^%$#@!", "...." ]
)]
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::case1autheduser::query1 ... ok test shouldbeinvalidqueryerror::case2guest::query2 ... ok test shouldbeinvalidqueryerror::case2guest::query3 ... ok test shouldbeinvalidqueryerror::case1autheduser::query2 ... ok test shouldbeinvalidqueryerror::case1autheduser::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 quite yet!
A fixture can be injected by another fixture and they can be called using just some of its arguments.
```rust
fn name() -> &'static str { "Alice" }
fn age() -> u8 { 22 }
fn user(name: &str, age: u8) -> User { User::new(name, age) }
fn isalice(user: User) { asserteq!(user.name(), "Alice") }
fn is22(user: User) { asserteq!(user.age(), 22) }
fn isbob(user: User) { asserteq!(user.name(), "Bob") }
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
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.
See CHANGELOG.md
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.