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

/// The assert module enables defining [test properties](https://antithesis.com/docs/using_antithesis/properties/)
/// about your program or [workload](https://antithesis.com/docs/getting_started/first_test/).
///
/// The constant [const@LOCAL_OUTPUT] is associated with local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview/#sdk-runtime-behavior) modes.
///
/// Each macro/function in this module takes a parameter called ``message``, which is
/// a string literal identifier used to aggregate assertions.
/// Antithesis generates one test property per unique ``message`` This test property will be named ``message`` in the [triage report](https://antithesis.com/docs/reports/triage/).
///
/// Each macro/function also takes a parameter called ``details``, which is a key-value map of optional additional information provided by the user to add context for assertion failures.
/// The information that is logged will appear in the ``logs`` section of a [triage report](https://antithesis.com/docs/reports/triage/).
/// Normally the values in ``details`` are evaluated at runtime.
pub mod assert;

// External crates used in assertion macros
#[doc(hidden)]
#[cfg(feature = "full")]
pub use linkme;
#[doc(hidden)]
#[cfg(feature = "full")]
pub use once_cell;
#[doc(hidden)]
#[cfg(feature = "full")]
pub use serde_json;

/// The lifecycle module contains functions which inform the Antithesis
/// environment that particular test phases or milestones have been reached.
/// 
/// The constant [const@LOCAL_OUTPUT] is associated with local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview/#sdk-runtime-behavior) modes.
pub mod lifecycle;

/// The random module provides functions that request both structured and unstructured randomness from the Antithesis environment.
///
/// These functions should not be used to seed a conventional PRNG, and should not have their return values stored and used to make a decision at a later time.
/// Doing either of these things makes it much harder for the Antithesis platform to control the history of your program's execution, and also makes it harder for Antithesis to learn which inputs provided at which times are most fruitful.
/// Instead, you should call a function from the random package every time your program or [workload](https://antithesis.com/docs/getting_started/first_test/) needs to make a decision, at the moment that you need to make the decision.
///
/// These functions are also safe to call outside the Antithesis environment, where
/// they will fall back on the rust std library implementation.
///
pub mod random;

mod internal;

/// Convenience to import all macros and functions
pub mod prelude;

/// Global initialization logic. Performs registration of the
/// Antithesis assertion catalog. This should be invoked as early as
/// possible during program execution. It is recommended to call it immediately in ``main``.
///
/// If called more than once, only the first call will result
/// in the assertion catalog being registered.  If never called,
/// the assertion catalog will be registered when it encounters the first assertion at runtime.
///
/// Example:
///
/// ```
/// use std::env;
/// use serde_json::{json};
/// use antithesis_sdk::{antithesis_init, assert_unreachable};
///
/// fn main() {
///     if (env::args_os().len() == 1888999778899) {
///         assert_unreachable!("Unable to provide trillions of arguments", &json!({}));
///     }
///     
///     // if antithesis_init() is omitted, the above unreachable will
///     // not be reported
///     antithesis_init();
/// }
/// ```
#[allow(clippy::needless_doctest_main)]
pub fn antithesis_init() {
    init();
}

#[cfg(feature = "full")]
fn init() {
    Lazy::force(&internal::LIB_HANDLER);
    Lazy::force(&assert::INIT_CATALOG);
}

#[cfg(not(feature = "full"))]
fn init() {}

#[cfg(feature = "full")]
use once_cell::sync::Lazy;

/// A constant provided by the SDK to report the location of logged output when run locally.
/// This constant is the name of an environment variable ``ANTITHESIS_SDK_LOCAL_OUTPUT``.
/// ``ANTITHESIS_SDK_LOCAL_OUTPUT`` is a path to a file 
/// that can be created and written to when running locally.  If this environment variable is not present at
/// runtime, then no assertion and lifecycle output will be attempted.
/// 
/// This allows you to make use of the Antithesis assertions module
/// in your regular testing, or even in production. In particular,
/// very few assertions frameworks offer a convenient way to define
/// [Sometimes assertions](https://antithesis.com/docs/best_practices/sometimes_assertions/), but they can be quite useful even outside
/// Antithesis.
/// 
/// See also the documentation for [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview/#sdk-runtime-behavior).
pub use crate::internal::LOCAL_OUTPUT;