P-test

This crate provides the p_test macro, which is to make writing parameterized tests easier.

Basic Usage

Suppose that you have a function you want to test.

fn sum(a: i32, b: i32) -> i32 {
    a + b
}

With p_test macro, you can write a parameterized test like this:

#[p_test(
    (1, 1, 2),
    (2, 3, 5),
    (4, 5, 9),
)]
fn test_sum(a: i32, b: i32, expected: i32) {
    assert_eq!(sum(a, b), expected);
}

The above code will be expanded like the below:

fn test_sum(expected: i32, a: i32, b: i32) {
    assert_eq!(sum(a, b), expected);
}

#[cfg(test)]
mod test_sum {
    use super::*;
    #[test]
    fn case_1() {
        test_sum(2, 1, 1);
    }
    #[test]
    fn case_2() {
        test_sum(5, 2, 3);
    }
    #[test]
    fn case_3() {
        test_sum(9, 4, 5);
    }
}

As you can see, the case names are auto-generated with case_{n} format. Note that the parameterized test function name test_sum is used for the module name. The test output will look like the following:

$ cargo test
...
test test_sum_no_name::case_1 ... ok
test test_sum_no_name::case_2 ... ok
test test_sum_no_name::case_3 ... ok

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

This is a handy way of writing parameterized tests. However, when you have a long list of parameters, finding a failed test would be challenging.

Use Arguments For Case Name

In any cases that the case name case_{n} is not good enough, you case use use_args_for_case_name=true. This direct p_test macro to use the values of the arguments for test case name generation.

#[p_test(
    use_args_for_case_name = true,
    (1, 1, 2),
    (2, 3, 5),
    (4, 5, 9),
)]
fn test_sum(a: i32, b: i32, expected: i32) {
    assert_eq!(sum(a, b), expected);
}

The test case names will be generated with the arguments, e.g. _1__1__2, so the output will look like the following:

$ cargo test
...
test test_sum::_1__1__2 ... ok
test test_sum::_2__3__5 ... ok
test test_sum::_4__5__9 ... ok
...

This will make it a little easier to locate the failed test case.

Specifying Explicit Case Names

If you prefer explicitness, you can specify each test case name like this:

#[p_test(
    sum_1_1, (1, 1, 2), // test case sum_1_1
    sum_2_3, (2, 3, 5), // test case sum_2_3
    sum_4_5, (4, 5, 9), // test case sum_4_5
)]
fn test_sum(a: i32, b: i32, expected: i32) {
    assert_eq!(sum(a, b), expected);
}

The first elements in each line (i.e., sum_1_1, sum_2_3, etc.) will be used as a test function names when the macro is expanded. So, they should be valid function names.

You can also use string literal for case name, like the following:

#[p_test(
    "sum(1,1)", (1, 1, 2),
    "sum(2,3)", (2, 3, 5),
    "sum(4,5)", (4, 5, 9),
)]
fn test_sum(a: i32, b: i32, expected: i32) {
    assert_eq!(sum(a, b), expected);
}

In this case, the case names will be transformed to a valid function names by replacing non-alphanumeric characters with _. For example, "sum(1,1)" will be converted to sum_1_1_.

The above code will be expanded like the below:

// This parameterized function is copied
fn test_sum(expected: i32, a: i32, b: i32) {
    assert_eq!(sum(a, b), expected);
}

// The macro expanded.
// Each of the case name become a test function
// which invokes parameterized function.
#[cfg(test)]
mod test_sum {
    use super::*;
    #[test]
    fn sum_1_1_() {
        test_sum(2, 1, 1);
    }
    #[test]
    fn sum_2_3_() {
        test_sum(5, 2, 3);
    }
    #[test]
    fn sum_4_5_() {
        test_sum(9, 4, 5);
    }
}

Parameter Order

We set the expected value at the end of each test case. But the order of arguments are totally up to you. You can use the first argument as an expected value.

#[p_test(
    sum_1_1, (2, 1, 1),
    sum_2_3, (5, 2, 3),
    sum_4_5, (9, 4, 5),
)]
fn test_sum(expected: i32, a: i32, b: i32) {
    assert_eq!(sum(a, b), expected);
}

But the order should match with the parameter list of the test function, test_sum in this example.

You can explicitly distinguish the argument list and the expected value like the below code, if you like.

use p_test::p_test;

#[p_test(
    sum_1_1, ((1, 1), 2),  // test case sum_1_1
    sum_2_3, ((2, 3), 5),  // test case sum_2_3
    sum_4_5, ((4, 5), 9),  // test case sum_4_5
)]
fn test_sum((a, b): (i32, i32), expected: i32) {
   assert_eq!(sum(a, b), expected);
}

Testing async function

p_test macro works well with tokio::test.

async fn sum(a: i32, b: i32) -> i32 {
    a + b
}

#[tokio::test]
#[p_test(
    sum_1_1, (1, 1, 2),
    sum_1_2, (1, 2, 3),
    sum_2_2, (2, 2, 4),
    sum_2_3, (2, 3, 5),
)]
async fn test_sum_async_tokio(a: i32, b: i32, expected: i32) {
    assert_eq!(sum(a, b).await, expected);
}

Note

There are breaking changes in 1.0.0.

• Before 1.0.0, you could explicitly specify test module name. It was required in the early versions, but became optional from 0.1.3. It is now removed for simplicity.
• The test case names used to be specified inside tuples. As of 0.1.8 it became possible to specify test case names by literal string. However, this caused an issue when the first parameter of the test function is string. Now, test case name should be specified before argument tuples.
• use_args_for_case_name is introduced.