C++ SDK#

The Antithesis C++ SDK provides a header file for placing your C++ code under test and using Antithesis functionality. It is available on Github.

See also a tutorial of how to use the SDK.

Header file#

The C++ SDK is distributed as a header file. This header file provides several types of functionality.

Three types of functionality are functions and macros:

  • The 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, the header file supports instrumenting C++ programs. There are several benefits of instrumentation when testing in Antithesis, such as more intelligent exploration.

Using the C++ SDK#

The basic workflow for using the C++ SDK is:

  1. Include the C++ header file in any .cpp or .h files that will use it. The header file is:

    #include "antithesis_sdk.h"
    
  2. Call SDK functions from your code. For example create a test property with an assertion such as assert.Always(some condition).

  3. Build your code by compiling and then linking it:

    • Use clang++ version 16 or higher. Contact us if you want to use a different compiler or a different version.

    • Use C++ version 20 or later. Enforce this with a compile flag, e.g. -std=c++20.

    • If you intend to deploy this build to Antithesis, ensure you both compile and link with instrumentation.

  4. 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. Minimal overhead, which skips over the function at minimal cost. This is the default when run outside of Antithesis.

  2. Local logging, which logs output locally in a structured JSON format. This mode is selected at run-time by setting the environment variable ANTITHESIS_SDK_LOCAL_OUTPUT to the full path of a file. The output of lifecycle and assert events will be logged there. The path must be relative to your current directory and should be set at program startup. E.g. ANTITHESIS_SDK_LOCAL_OUTPUT=assertions_20240520.json.

  3. Compile-time removal, which strips lifecycle and assert functions entirely from your code. This mode is selected at compile-time by #define-ing NO_ANTITHESIS_SDK in your code or at the command line. E.g. -D NO_ANTITHESIS_SDK. If you intend to test your build in Antithesis, then do not select this mode.

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.

Warning

Coverage instrumentation has a higher performance overhead than the SDK. We do not recommend running binaries with coverage instrumentation in production.