pbt 0.4.14

Property-based testing with `derive` macros, aware of mutual induction & instantiability.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

use {
    crate::{
        SEED, cache,
        construct::{Construct, arbitrary},
        shrink::shrink,
        size::Size,
    },
    core::fmt,
    std::env,
    wyrand::WyRand,
};

#[derive(Clone, Copy, Debug)]
#[expect(clippy::exhaustive_structs, reason = "genuinely exhaustive")]
pub struct Named<T> {
    pub name: &'static str,
    pub value: T,
}

#[expect(clippy::missing_trait_methods, reason = "intentionally left default")]
impl<T: Eq> Eq for Named<T> {}

#[expect(clippy::missing_trait_methods, reason = "intentionally left default")]
impl<T: PartialEq> PartialEq for Named<T> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        T::eq(&self.value, &other.value)
    }
}

#[inline]
pub fn witness<T: Construct, P: Fn(&T) -> bool>(n_cases: usize, property: P) -> Option<T> {
    let mut prng = WyRand::new(
        env::var("PBT_SEED")
            .ok()
            .and_then(|s| s.parse().ok())
            .unwrap_or_else(|| getrandom::u64().unwrap_or_else(|_| u64::from(SEED))),
    );
    for maybe_t in cache::load::<T>().into_iter().map(Some).chain(
        Size::expanding()
            .take(n_cases)
            .map(|size| arbitrary::<T>(&mut prng, size)),
    ) {
        let t = maybe_t?;
        if property(&t) {
            let mut best_yet = t;
            'restart: loop {
                for candidate in shrink::<T>(best_yet.clone()) {
                    if property(&candidate) {
                        best_yet = candidate;
                        continue 'restart;
                    }
                }
                // nothing better, so return our best-yet as the best overall:
                cache::store(&best_yet);
                return Some(best_yet);
            }
        }
    }
    None
}

/// Assert that some property always holds (i.e. returns `true`).
/// # Panics
/// If a minimal witness can be found
/// by checking up to `n_cases` cases
/// for which the property returns `false`.
#[inline]
#[expect(clippy::panic, reason = "failing assertions ought to panic")]
pub fn assert<T: Construct, P: Fn(&T) -> bool>(n_cases: usize, property: P) {
    if let Some(t) = witness(n_cases, |t| !property(t)) {
        assert!(
            property(&t),
            "\r\n\r\nnot always true: for example, consider the input\r\n{t:#?}\r\n\r\n",
        );
        panic!(
            "\r\n\r\nflaky test! the input\r\n{t:#?}\r\noriginally returned `{:?}`, but when run again, it returned `{:?}`\r\n\r\n",
            false, true,
        )
    }
}

/// Assert that two terms (which may vary
/// depending on some input) are always equal.
/// # Panics
/// If a minimal witness can be found
/// by checking up to `n_cases` cases
/// for which the two terms differ.
#[inline]
#[expect(clippy::panic, reason = "failing assertions ought to panic")]
pub fn assert_eq<X: Construct, Y: fmt::Debug + Eq, P: Fn(&X) -> (Y, Y)>(
    n_cases: usize,
    property: P,
) {
    if let Some(x) = witness(n_cases, |x| {
        let (lhs, rhs) = property(x);
        lhs != rhs
    }) {
        let (lhs, rhs) = property(&x);
        pretty_assertions::assert_eq!(
            lhs,
            rhs,
            "\r\n\r\nnot always equal: for example, consider the input\r\n{x:#?}\r\n\r\n",
        );
        panic!(
            "\r\n\r\nflaky test! the input\r\n{x:#?}\r\noriginally failed, but when run again, it produced\r\n{lhs:#?}\r\nand\r\n{rhs:#?}\r\nwhich were judged to be equal\r\n\r\n",
        )
    }
}