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
• Return types
• Function qualifiers
• Global #[parameterized(,,,)] import
• License

Examples ^{(back to top)}

A first example

fn add5<T: Into<u32>>(component: T) -> u32 {
    component.into() + 5
}

#[cfg(test)]
mod tests {
    use super::*;
    use yare::parameterized;

    #[parameterized(
        zero_plus_five = { 0, 5 },
        one_plus_five = { 1, 6 },
        two_plus_five = { 2, 7 },
    )]
    fn test_add5(input: u16, expected: u32) {
        assert_eq!(add5(input), expected);
    }
}

An example with values

enum Fruit {
    Apple,
    Bramble(BrambleFruit),
    Pear,
}

trait NameOf {
    fn name_of(&self) -> &str;
}

impl NameOf for Fruit {
    fn name_of(&self) -> &str {
        match self {
            Fruit::Apple => "apple",
            Fruit::Bramble(fruit) => fruit.name_of(),
            Fruit::Pear => "pear",
        }
    }
}

enum BrambleFruit {
    Blackberry,
}

impl NameOf for BrambleFruit {
    fn name_of(&self) -> &str {
        match self {
            BrambleFruit::Blackberry => "blackberry",
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use yare::parameterized;

    #[parameterized(
        apple = { Fruit::Apple, "apple" },
        pear = { Fruit::Pear, "pear" },
        blackberry = { Fruit::Bramble(BrambleFruit::Blackberry), "blackberry" },
    )]
    fn a_fruity_test(fruit: Fruit, name: &str) {
        assert_eq!(fruit.name_of(), name)
    }
}

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 std::sync::atomic::{AtomicU32, Ordering};
use yare::parameterized;

#[parameterized(
    seeding_randomness_with_two_dice_rolls = { 
        roll_dice(&AtomicU32::new(0)),                                      // <- This is an expression (a function call)
        {                                                                   // <- This is also an expression (a block expression)
            let from_half = roll_dice( & AtomicU32::new(u32::MAX / 2));
            let from_max = roll_dice( & AtomicU32::new(u32::MAX));
            
            u8::min(from_half, from_max)
        }
    }
)]
fn dicey(seed1: u8, seed2: u8) {
    // Creating a base seed in a complicated way for the sake of it.
    let max = u8::max(seed1, seed2);
    let seed = AtomicU32::new(u32::from(max));

    let out_of_bounds_values = (0..1000)         // roll the dice 1000 times
        .map(|_| roll_dice(&seed))
        .find(|value| !(1..=6).contains(value)); // check that the outputs of the dice are just 1, 2, 3, 4, 5 or 6. 

    assert!(out_of_bounds_values.is_none());
}

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 yare::parameterized;

#[parameterized(
    ok = { Ok(0) },
    // err = {  Err("noes!".to_string()) }, <-- enabling this would result in a failed test, since the error code will not be an `ErrorCode::Success`. See the `Termination` trait for more.
)]
fn test(value: Result<u32, String>) -> Result<(), String> {
    let v = value?;
    
    assert_eq!(v.unwrap(), 0);
}

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 yare::parameterized;

#[parameterized(
    purple = { &[128, 0, 128] },
    orange = { &[255, 127, 0] },
)]
const extern "C" fn has_reds(streamed_color: &[u8]) {
    assert!(streamed_color.first().is_some());
}

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:

#[cfg(test)]
#[macro_use]
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.