behave 0.9.1

BDD testing framework with expressive expect! matchers and a zero-keyword DSL.
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
110
111
112
113
114
115
116
117
118

//! Custom matcher trait for user-defined matchers.

use crate::error::MatchError;
use crate::expectation::Expectation;

/// Trait for implementing custom matchers.
///
/// Implement this trait on your own types to create reusable matchers
/// that work with [`Expectation::to_match`].
///
/// For one-off checks, prefer
/// [`to_satisfy(predicate, description)`](crate::Expectation::to_satisfy)
/// which takes a closure. Use `BehaveMatch` when you want a named,
/// reusable matcher — especially for domain rules used across many tests.
///
/// # Examples
///
/// ```
/// use behave::{BehaveMatch, Expectation, MatchError};
///
/// struct IsEven;
///
/// impl BehaveMatch<i32> for IsEven {
///     fn matches(&self, actual: &i32) -> bool {
///         actual % 2 == 0
///     }
///
///     fn description(&self) -> &str {
///         "to be even"
///     }
/// }
///
/// let result = Expectation::new(4, "4").to_match(IsEven);
/// assert!(result.is_ok());
/// ```
pub trait BehaveMatch<T> {
    /// Returns `true` if the actual value satisfies the matcher.
    fn matches(&self, actual: &T) -> bool;

    /// Returns a human-readable description of what the matcher expects.
    fn description(&self) -> &str;
}

impl<T> BehaveMatch<T> for Box<dyn BehaveMatch<T>> {
    fn matches(&self, actual: &T) -> bool {
        (**self).matches(actual)
    }

    fn description(&self) -> &str {
        (**self).description()
    }
}

impl<T: core::fmt::Debug> Expectation<T> {
    /// Asserts the value satisfies a custom [`BehaveMatch`] matcher.
    ///
    /// # Errors
    ///
    /// Returns [`MatchError`] if the value does not match (or matches when negated).
    ///
    /// # Examples
    ///
    /// ```
    /// use behave::{BehaveMatch, Expectation, MatchError};
    ///
    /// struct IsPositive;
    /// impl BehaveMatch<i32> for IsPositive {
    ///     fn matches(&self, actual: &i32) -> bool { *actual > 0 }
    ///     fn description(&self) -> &str { "to be positive" }
    /// }
    ///
    /// let result = Expectation::new(5, "5").to_match(IsPositive);
    /// assert!(result.is_ok());
    /// ```
    #[allow(clippy::needless_pass_by_value)]
    pub fn to_match(&self, custom: impl BehaveMatch<T>) -> Result<(), MatchError> {
        let is_match = custom.matches(self.value());
        self.check(is_match, custom.description())
    }
}

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

    struct IsEven;

    #[allow(clippy::unnecessary_literal_bound)]
    impl BehaveMatch<i32> for IsEven {
        fn matches(&self, actual: &i32) -> bool {
            actual % 2 == 0
        }

        fn description(&self) -> &str {
            "to be even"
        }
    }

    #[test]
    fn custom_matcher_pass() {
        assert!(Expectation::new(4, "4").to_match(IsEven).is_ok());
    }

    #[test]
    fn custom_matcher_fail() {
        assert!(Expectation::new(3, "3").to_match(IsEven).is_err());
    }

    #[test]
    fn custom_matcher_negated_pass() {
        assert!(Expectation::new(3, "3").negate().to_match(IsEven).is_ok());
    }

    #[test]
    fn custom_matcher_negated_fail() {
        assert!(Expectation::new(4, "4").negate().to_match(IsEven).is_err());
    }
}