Antithesis C++ SDK

Overview

The Antithesis C++ SDK is a header-only library for integration your C++ code with Antithesis. It is available on Github.

The Antithesis C++ SDK is intended for use with C++ version 20 or later and Clang version 16 or higher. Contact us if you want to use a different compiler or a different version.

SDK functionality

Most of the functionality of the C++ SDK is contained in the header file antithesis_sdk.h. This file provides three main types of functionality:

• 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.

Coverage instrumentation

There is a secondary header file, antithesis_instrumentation.h, which is packaged with the C++ SDK. This file supports instrumenting C and C++ programs. There are several benefits of instrumentation when testing in Antithesis, such as more intelligent exploration.

This header file must be included in one, and only one, translation unit. We recommend including it wherever you have defined the main function.

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.

Further reading

• Tutorial
• C/C++ Instrumentation
• Assert (reference)
• Lifecycle (reference)
• Random (reference)
• Legacy C/C++ Instrumentation