precept 0.3.0

A testing utility for fuzzing and fault injection to discover erroneous and interesting states.
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
119
120
121
122
123
124
125
126
127
128
129

use std::{
    panic::Location,
    sync::{
        LazyLock,
        atomic::{self, AtomicUsize},
    },
};

use crate::dispatch::{self, Event, dispatcher};

/// Catalog of all antithesis assertions provided
#[cfg(feature = "enabled")]
#[linkme::distributed_slice]
pub static PRECEPT_CATALOG: [CatalogEntry];

#[cfg(not(feature = "enabled"))]
pub static PRECEPT_CATALOG: [&CatalogEntry; 0] = [];

pub(crate) fn init_catalog() {
    let dispatch = dispatcher();
    for entry in PRECEPT_CATALOG {
        dispatch.emit(Event::RegisterEntry(entry));
    }
}

#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum Expectation {
    Always,
    AlwaysOrUnreachable,
    Sometimes,
    Reachable,
    Unreachable,
}

impl Expectation {
    pub fn check(self, condition: bool) -> bool {
        use Expectation::*;

        match (self, condition) {
            (Always | AlwaysOrUnreachable, out) => out,
            (Sometimes | Reachable, _) => true,
            (Unreachable, _) => false,
        }
    }
}

#[derive(Debug)]
pub struct CatalogEntry {
    // the type of this expectation
    expectation: Expectation,
    // the name of the entry, also serves as its id
    property: &'static str,
    // panic::Location::caller()
    location: &'static Location<'static>,
    // from module_path!()
    module: &'static str,
    // from function_name!()
    function: &'static LazyLock<&'static str>,

    // the number of times this entry has been encountered with a true condition
    pass_count: AtomicUsize,
    // the number of times this entry has been encountered with a false condition
    fail_count: AtomicUsize,
}

impl CatalogEntry {
    pub const fn new(
        expectation: Expectation,
        property: &'static str,
        location: &'static Location<'static>,
        module: &'static str,
        function: &'static LazyLock<&'static str>,
    ) -> Self {
        Self {
            expectation,
            property,
            location,
            module,
            function,
            pass_count: AtomicUsize::new(0),
            fail_count: AtomicUsize::new(0),
        }
    }

    pub fn emit(&'static self, condition: bool, details: serde_json::Value) {
        let count = if condition {
            self.pass_count.fetch_add(1, atomic::Ordering::AcqRel)
        } else {
            self.fail_count.fetch_add(1, atomic::Ordering::AcqRel)
        };
        // only emit on the first pass or fail
        if count == 0 {
            dispatch::emit(Event::EmitEntry { entry: self, condition, details });
        }
    }

    #[inline]
    pub fn expectation(&self) -> Expectation {
        self.expectation
    }

    #[inline]
    pub fn property(&self) -> &'static str {
        self.property
    }

    #[inline]
    pub fn location(&self) -> &'static Location<'static> {
        self.location
    }

    #[inline]
    pub fn module(&self) -> &'static str {
        self.module
    }

    #[inline]
    pub fn function(&self) -> &'static str {
        self.function
    }

    pub fn pass_count(&self) -> usize {
        self.pass_count.load(atomic::Ordering::Acquire)
    }

    pub fn fail_count(&self) -> usize {
        self.fail_count.load(atomic::Ordering::Acquire)
    }
}