From 3ad9b301877c448da29b6e0020673de430db1d2c Mon Sep 17 00:00:00 2001 From: Kevin Hawickhorst Date: Tue, 14 May 2024 12:01:20 -0400 Subject: [PATCH 1/5] Fixing a few missed code snippets --- lib/src/assert/macros.rs | 2 +- lib/src/assert/mod.rs | 8 ++++---- lib/src/lib.rs | 11 +++++------ lib/src/random.rs | 2 +- 4 files changed, 11 insertions(+), 12 deletions(-) diff --git a/lib/src/assert/macros.rs b/lib/src/assert/macros.rs index aaa5529..4ac2818 100644 --- a/lib/src/assert/macros.rs +++ b/lib/src/assert/macros.rs @@ -80,7 +80,7 @@ macro_rules! assert_helper { } /// Assert that ``condition`` is true every time this function is called, **and** that it is -/// called at least once. The corresponding test property will be viewable in the Antithesis SDK: Always group of your triage report. +/// called at least once. The corresponding test property will be viewable in the ``Antithesis SDK: Always`` group of your triage report. /// /// # Example /// diff --git a/lib/src/assert/mod.rs b/lib/src/assert/mod.rs index 3370f66..dcd6ae8 100644 --- a/lib/src/assert/mod.rs +++ b/lib/src/assert/mod.rs @@ -16,8 +16,8 @@ pub static ANTITHESIS_CATALOG: [CatalogInfo]; // Only need an ASSET_TRACKER if there are actually assertions 'hit' // (i.e. encountered and invoked at runtime). // -// Typically runtime assertions use the macros always!(), sometimes!(), etc. -// or, a client is using the 'raw' interface 'assert_raw' at runtime. +// Typically runtime assertions use the macros ``always!``, ``sometimes!``, etc. +// or, a client is using the 'raw' interface ``assert_raw`` at runtime. // pub(crate) static ASSERT_TRACKER: Lazy>> = Lazy::new(|| Mutex::new(HashMap::new())); @@ -206,8 +206,8 @@ impl AssertionInfo { /// assertions. /// /// Be certain to provide an assertion catalog entry -/// for each assertion issued with assert_raw(). Assertion catalog -/// entries are also created useing assert_raw(), by setting the value +/// for each assertion issued with ``assert_raw()``. Assertion catalog +/// entries are also created using ``assert_raw()``, by setting the value /// of the ``hit`` parameter to false. /// /// Please refer to the general Antithesis documentation regarding the diff --git a/lib/src/lib.rs b/lib/src/lib.rs index 49aa0e1..6d3bd7a 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -48,15 +48,14 @@ pub mod prelude; /// Global initialization logic. Performs registration of the /// Antithesis assertion catalog. This should be invoked as early as -/// possible during program execution (invoke first thing in main). +/// possible during program execution. It is recommended to call immediately in main. /// -/// If invoked more than once, only the first call will result -/// in the assertion catalog being registered. If not invoked at all, -/// the assertion catalog will be registered upon the first -/// assertion that is encountered at runtime. +/// 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. /// /// Warning - if assertions are included in a program, and not -/// encountered at runtime, and antithesis_init() has not been +/// encountered at runtime, and ``antithesis_init()`` has not been /// called, then the assertions will not be reported. /// /// Example: diff --git a/lib/src/random.rs b/lib/src/random.rs index 1b23766..bb087c4 100644 --- a/lib/src/random.rs +++ b/lib/src/random.rs @@ -1,6 +1,6 @@ use crate::internal; -/// Returns a uint64 value chosen by Antithesis. You should not +/// Returns a u64 value chosen by Antithesis. You should not /// store this value or use it to seed a PRNG, but should use it /// immediately. /// From a667ffc0d0f53eaf11dea1ce1c5471ed8fef8931 Mon Sep 17 00:00:00 2001 From: Kevin Hawickhorst Date: Tue, 14 May 2024 14:03:26 -0400 Subject: [PATCH 2/5] Making Will's improvements --- lib/src/lib.rs | 22 +++++++++------------- lib/src/lifecycle.rs | 2 +- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/lib/src/lib.rs b/lib/src/lib.rs index 6d3bd7a..0cf9c1a 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -1,15 +1,7 @@ /// The assert module enables defining [test properties](https://antithesis.com/docs/using_antithesis/properties.html) /// about your program or [workload](https://antithesis.com/docs/getting_started/workload.html). /// -/// Whenever the environment variable ``ANTITHESIS_SDK_LOCAL_OUTPUT`` is -/// set, these macros and functions will log to the file pointed -/// to by that variable using a structured JSON format defined in -/// the [Antithesis SDK docs](https://antithesis.com/docs/using_antithesis/sdk/fallback/assert.html#syntax). -/// 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.html), but they can be quite useful even outside -/// Antithesis. +/// The environment variable [const@LOCAL_OUTPUT] may be used for local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#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. @@ -54,10 +46,6 @@ pub mod prelude; /// in the assertion catalog being registered. If never called, /// the assertion catalog will be registered when it encounters the first assertion at runtime. /// -/// Warning - if assertions are included in a program, and not -/// encountered at runtime, and ``antithesis_init()`` has not been -/// called, then the assertions will not be reported. -/// /// Example: /// /// ``` @@ -87,4 +75,12 @@ use once_cell::sync::Lazy; /// that can be created and written to when not running in the Antithesis /// Testing environment. 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.html), 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.html#sdk-runtime-behavior). pub use crate::internal::LOCAL_OUTPUT; diff --git a/lib/src/lifecycle.rs b/lib/src/lifecycle.rs index bd7ff9e..0a90046 100644 --- a/lib/src/lifecycle.rs +++ b/lib/src/lifecycle.rs @@ -45,7 +45,7 @@ pub fn setup_complete(details: &Value) { /// Indicates to Antithesis that a certain event has been reached. It sends a structured log message to Antithesis that you may later use to aid debugging. /// -/// In addition to ``details``, you also provide ``name``, which is the name of the event that you are logging. This name will appear in the ``logs`` section of a [triage report](https://antithesis.com/docs/reports/triage.html). +/// In addition to ``details``, you also provide ``name``, which is the name of the event that you are logging. /// /// # Example /// From 2f8c14494c61ca2500689bee47b2d488f3115bf1 Mon Sep 17 00:00:00 2001 From: Kevin Hawickhorst Date: Tue, 14 May 2024 14:05:05 -0400 Subject: [PATCH 3/5] Adding a warning to lifecycle to match assert --- lib/src/lib.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/src/lib.rs b/lib/src/lib.rs index 0cf9c1a..4c094de 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -20,6 +20,8 @@ pub use once_cell; /// The lifecycle module contains functions which inform the Antithesis /// environment that particular test phases or milestones have been reached. +/// +/// The environment variable [const@LOCAL_OUTPUT] may be used for local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior) modes. pub mod lifecycle; /// The random module provides functions that request both structured and unstructured randomness from the Antithesis environment. From 70ba55d76a2aa78bd8f80c645255da5765772226 Mon Sep 17 00:00:00 2001 From: Kevin Hawickhorst Date: Tue, 14 May 2024 14:38:16 -0400 Subject: [PATCH 4/5] Improving description of the constant --- lib/src/lib.rs | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/lib/src/lib.rs b/lib/src/lib.rs index 4c094de..3d66017 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -1,7 +1,7 @@ /// The assert module enables defining [test properties](https://antithesis.com/docs/using_antithesis/properties.html) /// about your program or [workload](https://antithesis.com/docs/getting_started/workload.html). /// -/// The environment variable [const@LOCAL_OUTPUT] may be used for local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior) modes. +/// 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.html#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. @@ -21,7 +21,7 @@ pub use once_cell; /// The lifecycle module contains functions which inform the Antithesis /// environment that particular test phases or milestones have been reached. /// -/// The environment variable [const@LOCAL_OUTPUT] may be used for local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior) modes. +/// 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.html#sdk-runtime-behavior) modes. pub mod lifecycle; /// The random module provides functions that request both structured and unstructured randomness from the Antithesis environment. @@ -40,9 +40,9 @@ 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 immediately in main. +/// 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, @@ -73,9 +73,10 @@ pub fn antithesis_init() { use once_cell::sync::Lazy; -/// The name of the environment variable containing a path to a file -/// that can be created and written to when not running in the Antithesis -/// Testing environment. If this environment variable is not present at +/// 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 From 18070d9502e103ab117d7913b50b21151d2da754 Mon Sep 17 00:00:00 2001 From: Paul Herzog Date: Tue, 14 May 2024 14:59:00 -0400 Subject: [PATCH 5/5] Update version to v0.1.5 --- Cargo.lock | 2 +- lib/Cargo.lock | 2 +- lib/Cargo.toml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 119ee11..0df1730 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,7 +4,7 @@ version = 3 [[package]] name = "antithesis_sdk" -version = "0.1.4" +version = "0.1.5" dependencies = [ "libc", "libloading", diff --git a/lib/Cargo.lock b/lib/Cargo.lock index 7801466..75665b3 100644 --- a/lib/Cargo.lock +++ b/lib/Cargo.lock @@ -4,7 +4,7 @@ version = 3 [[package]] name = "antithesis_sdk_rust" -version = "0.1.4" +version = "0.1.5" dependencies = [ "lazy_static", "libc", diff --git a/lib/Cargo.toml b/lib/Cargo.toml index 3b78f81..cd23a04 100644 --- a/lib/Cargo.toml +++ b/lib/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "antithesis_sdk" -version = "0.1.4" +version = "0.1.5" edition = "2021" rust-version = "1.62.1" license = "MIT"