Crate dicetest

Dicetest is a framework for writing tests with pseudorandom generated test data.

Status of this crate

The author does not consider this crate as stable yet.

Simple example

Here's an example of a broken sort function tested with Dicetest:

fn bubble_sort<T: Ord>(slice: &mut [T]) {
    let len = slice.len();

    for _ in 0..len {
        for j in 1..len - 1 {
            let jpp = j + 1;
            if slice[j] > slice[jpp] {
                slice.swap(j, jpp);
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use dicetest::prelude::tests::*;

    #[test]
    fn result_of_bubble_sort_is_sorted() {
        dicetest!(|fate| {
            let mut v = dice::vec(dice::u8(..), ..).roll(fate);
            hint!("unsorted: {:?}", v);

            bubble_sort(&mut v);
            hint!("  sorted: {:?}", v);

            let is_sorted = v.windows(2).all(|w| w[0] <= w[1]);
            assert!(is_sorted);
        })
    }
}

Running cargo test produces the following output:

The test failed after 36 passes.

# Config
- seed: 795359663177100823
- start limit: 0
- end limit: 100
- passes: 1000

# Counterexample
- run code: "ABIDje/+CYVkmmCVTwKJ2go6VrzZWMjO2Bqc9m3b3h0DAAAAAAAAAA=="
- limit: 3
- hints:
    - unsorted: [255, 252, 131]
    -   sorted: [255, 131, 252]
- error: assertion failed: is_sorted

You can rerun the counterexample by setting a environment variable:

DICETEST_DEBUG=ABIDje/+CYVkmmCVTwKJ2go6VrzZWMjO2Bqc9m3b3h0DAAAAAAAAAA== cargo test

Alternatives

• Write down your test data and use a loop.
• Use the crate quickcheck.
• Use the crate proptest.

Modules

checker	A unit-test friendly interface for the runner that panics once the test failed.
codice	The standard collection of Codie implementations.
codie	Provides the trait Codie for converting values into a seed.
dice	The standard collection of DieOnce and Die implementations.
die	Provides the traits DieOnce and Die for generating pseudorandom values.
formatter	Converts runner results to human-readable strings.
hints	Hints help to analyze a single test run, mostly the counterexample.
prand	Provides the types Seed and Prng for using pseudorandomness.
prelude	Contains preludes for different use cases.
runner	The runner tries to falsify the assertions of a test by running it repeatedly with different seeds and aborts once a counterexample has been found.
stats	Stats help to analyze repeated test runs.

Macros

dicetest	Checks the test with checker::check. The config can be omitted.
hint	Adds a hint that contains the arguments applied to the format macro.
hint_debug	Adds a hint that contains the stringified argument and the argument value converted with Debug.
stat	Creates a stat with the first argument as stat key and the remaining arguments applied to the format macro as stat value.
stat_debug	Creates a stat with the stringified argument as stat key and the argument value converted with Debug as stat value.