Yare ⛵
Procedural macro based parameterized testing library. Run a test case with many different inputs. Test cases can be defined using the 'parameterized' attribute instead of the 'test' attribute.
Features
- Parameterization: Specify different inputs to test multiple scenarios with a single test definition.
- Flexible: Parameterized test case arguments are expressions.
- Out of the box experience: Works with any Rust version out of the box. No custom test harness necessary.
- Reusable: Promotes code reuse by defining test cases once and using them with different parameters across multiple tests.
- Readable: Maintains readability by using a familiar Rustic attribute syntax.
- Identifiable: Each test case has a user defined name which can be referred back to, and can be used to run individual test cases.
- Battle tested: Used for years in tests of the cargo-msrv, bisector and rust-releases crates (amongst others).
Table of contents
- Introduction
- Examples
- Arguments are expressions
- Custom test macro (e.g. tokio::test)
- Return types
- Function qualifiers
- Global #[parameterized(,,,)] import
- License
Examples (back to top)
A first example
An example with values
Arguments are expressions (back to top)
While the arguments above were simple values, any expression can be used as argument in a test case.
Example
In the example below, we roll the dice 3 times to generate a seed for later roll_dice function calls.
The first argument seed1
is a function call to roll_dice. This randomness function is seeded with value 0
.
The second argument seed2
is a block expression. In the expression the roll_dice function is called twice.
The test itself takes the maximum of seed1
and seed2
, rolls the die 1000 times, and checks that all values
are valid for a d6 die.
use ;
use parameterized;
Custom test macro (e.g. tokio::test) (back to top)
By default, the code generation step of the parameterized
attribute will generate test cases marked with a #[test]
attribute. For example, the add5
test from the examples would generate something like:
However, sometimes a different test macro is desired. An example is when writing tests for projects which depend on tokio.
For this, you may want to use #[tokio::test]
(it also requires the test function to also have the async
qualifier).
In Yare, it is possible to specify a custom test macro. To do so, you may add the #[test_macro(...)]
attribute after
a #[parameterized]
attribute.
Custom test macro example: tokio::test
use parameterized;
async
Gotchas:
- The
#[test_macro(...)]
must always be specified after a#[parameterized(...)]
attribute. - Only one
#[test_macro(...)]
attribute per parameterized test function is allowed. - While you can rename the parameterized attribute using import aliassing (
e.g.
use yare::parameterized as pm
), thetest_macro
attribute cannot be renamed, since it's not actually defined as a separate macro. Instead, theparameterized
macro parses this attribute as well.
Return types (back to top)
Yare supports specifying a return type for a parameterized test function.
Note that the underlying test attribute must also have support for return types. By default, Yare generates individual test cases decorated with the familiar test attribute, which is included with any Rust distribution by default.
Example
use parameterized;
Function qualifiers (back to top)
Yare supports the following function qualifiers: const
, async
, unsafe
and extern
.
This is particularly useful if you use #[parameterized(...)]
with a custom test macro such as tokio::test
, instead
of the built-in test macro.
Example
use parameterized;
const extern "C"
Globally importing parameterized (back to top)
If you prefer not to import this library (with use yare::parameterized;
) in every test module, you can put
the following snippet at the top of your crate root:
extern crate yare;
License (back to top)
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.