> ## Rust SDK

> Rust SDK for Antithesis

> Fetch the complete documentation index at: https://antithesis.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---

## Overview

The Antithesis Rust SDK crate provides *modules* for placing your Rust code under test and using Antithesis functionality.
It is [available on Github](https://github.com/antithesishq/antithesis-sdk-rust/) and [on crates.io](https://crates.io/crates/antithesis_sdk).

### 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](/docs/generated/sdk/rust/antithesis_sdk/assert) macros define [test properties](/docs/concepts/properties_assertions/properties/) about your software or workload.
- The [random](/docs/generated/sdk/rust/antithesis_sdk/random/) functions request both structured and unstructured randomness from the Antithesis platform.
- The [lifecycle](/docs/generated/sdk/rust/antithesis_sdk/lifecycle) functions inform the Antithesis environment that particular test phases or milestones have been reached.

Additionally, there is a top-level function, [Antithesis init](/docs/generated/sdk/rust/antithesis_sdk/fn.antithesis_init.html).
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](https://www.crates.io) for the specific version.

```toml
[package]
name = "simple"
version = "0.1.0"
edition = "2021"

[dependencies]
antithesis_sdk = "0.1.5"
serde_json = "1.0.25"
```

2. Call `antithesis_init()` at the beginning of your program.

3. Call other SDK functions from your code. For example [create a test property with an assertion](/docs/concepts/properties_assertions/properties/)
   such as `assert_always!(bool_expression, ...other_args);`

4. Build your code:

```bash
cargo build
```

> **Note**
>
> If you intend to deploy this build to Antithesis, ensure you build with [instrumentation](/docs/reference/sdk/rust/instrumentation/).

5. 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](/docs/concepts/properties_assertions/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](/docs/generated/sdk/rust/antithesis_sdk/assert) macros and [lifecycle](/docs/generated/sdk/rust/antithesis_sdk/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](/docs/reference/sdk/fallback/schema/).

   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:

```toml
[package]
name = "simple"
version = "0.1.0"
edition = "2021"

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

> **Tip**
>
> 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:
>
> ```toml
> [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](/docs/generated/sdk/rust/antithesis_sdk/random/) functions fall back upon the [standard library's random](https://docs.rs/rand/latest/rand) for entropy when run outside of Antithesis. This can be overridden so as to fall back upon a different library; see [random](/docs/generated/sdk/rust/antithesis_sdk/random/) for details.