Skip to main content

​
Overview

The Antithesis Rust SDK crate provides modules for placing your Rust code under test and using Antithesis functionality. It is available on Github and on crates.io.

​
Modules

The Rust SDK is distributed as a crate containing several modules. Each of the three modules provides a separate type of functionality:
  • The rust assert macros define test properties about your software or workload.
  • The random functions request both structured and unstructured randomness from the Antithesis platform.
  • The lifecycle functions inform the Antithesis environment that particular test phases or milestones have been reached.
Additionally, there is a top-level function, Antithesis init. This function must be called as soon as possible at program setup in order for assertions and other features to work properly.

​
Using the Rust SDK

The basic workflow for using the Rust SDK is:
  1. Include it as a dependency in Cargo.toml. Check crates for the specific version.
[package]
name = "simple"
version = "0.1.0"
edition = "2021"

[dependencies]
antithesis_sdk = "0.1.5"
serde_json = "1.0.25"
  1. Call antithesis_init() at the beginning of your program.
  2. Call other SDK functions from your code. For example create a test property with an assertion such as assert_always!(bool_expression, ...other_args);
  3. Build your code: 
cargo build
If you intend to deploy this build to Antithesis, ensure you build with instrumentation.
  1. Deploy your build: either to Antithesis or into production.

​
SDK runtime behavior

When your code is run outside Antithesis, our SDK has sensible fallback behavior with minimal performance overhead. This enables you to have a single build of your software that runs both inside and outside Antithesis. One benefit of this is that Sometimes Assertions continue to function outside Antithesis, and can be quite useful for discovering what states of your program are encountered during real-world use. The assert macros and lifecycle functions have three possible modes for local execution:
  1. Default, where assert and lifecycle use local implementations of Antithesis functionality. However, the results will not be logged anywhere because no logfile has been specified. This mode is enabled by the full feature flag. The flag is enabled by default.
  2. Default with logging, which is the same as the above but logs output locally in a structured JSON format. This mode is selected at runtime by setting the environment variable ANTITHESIS_SDK_LOCAL_OUTPUT at program startup. This variable must be set to a filepath: a logfile will be created at this location. The file must be located inside an already-existing directory. You may supply either a relative or absolute path. For example, you could set ANTITHESIS_SDK_LOCAL_OUTPUT=assertions_20240520.json at startup to implement this mode.
  3. No-op, which disables lifecycle and assert calls and skips over them at low cost. In particular, the arguments to these functions are evaluated, but the functions are stubbed-out. This mode is selected at build-time by disabling all default features for the sdk crate. For example, your Cargo.toml might look like the following: 
[package]
name = "simple"
version = "0.1.0"
edition = "2021"

[dependencies]
antithesis_sdk = { version = "0.2.1", default-features = false }
serde_json = "1.0.25"
You might want to make the SDK no-op by default. To do so, create your own feature that conditionally enables the Antithesis SDK. For example, your Cargo.toml might look like the following:
[package]
name = "simple"
version = "0.1.0"
edition = "2021"

[dependencies]
antithesis_sdk = { version = "0.2.1", default-features = false }
serde_json = "1.0.25"


[features]
running_in_antithesis = ["antithesis_sdk/full"] # control if full is set or not
Now, you can enable the running_in_antithesis flag for builds you send to Antithesis. You can leave it disabled for production builds.
The random functions fall back upon the standard library’s random for entropy when run outside of Antithesis. This can be overridden so as to fall back upon a different library; see random for details.

​
Further reading