Assert macros (C++ SDK)

Assert macros define test properties about your software or workload. They are defined as part of the Antithesis C++ SDK.

Macros

Always

ALWAYS(bool condition, const char* message, JSON details)

Asserts that condition is true every time this macro 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.

Parameters: See common parameters below. Note in particular that the precise data type of details is described there.

Example

#include <antithesis_sdk.h>
// ...
int bar(int x, int y){
    ALWAYS(x > 0, "x is positive", {{"x", x}});
    // Include the value of x to help debug if this fails
}

Always or unreachable

ALWAYS_OR_UNREACHABLE(bool condition, const char* message, JSON details)

Asserts that condition is true every time this macro is called. The corresponding test property will pass if the assertion is never encountered (unlike Always assertion types). This test property will be viewable in the “Antithesis SDK: Always” group of your triage report.

Parameters: See common parameters below. Note in particular that the precise data type of details is described there.

Sometimes

SOMETIMES(bool condition, const char* message, JSON details)

Asserts that condition is true at least one time that this macro was called. (If the assertion is never encountered, the test property will therefore fail.) This test property will be viewable in the “Antithesis SDK: Sometimes” group.

Parameters: See common parameters below. Note in particular that the precise data type of details is described there.

Reachable

REACHABLE(const char* message, JSON details)

Assert that a line of code is reached at least once. The corresponding test property will pass if this macro is ever called. (If it is never called the test property will therefore fail.) This test property will be viewable in the “Antithesis SDK: Reachablity assertions” group.

Parameters: See common parameters below. Note in particular that the precise data type of details is described there.

Unreachable

UNREACHABLE(const char* message, JSON details)

Assert that a line of code is never reached. The corresponding test property will fail if this macro is ever called. (If it is never called the test property will therefore pass.) This test property will be viewable in the “Antithesis SDK: Reachablity assertions” group.

Parameters: See common parameters below. Note in particular that the precise data type of details is described there.

Common parameters

condition

const bool. The result of evaluating the desired test condition. Normally the result passed to condition is evaluated at runtime.

message

const char* that must be known at compile time. A human readable identifier used to aggregate assertions. Antithesis generates one test property per unique message and this test property will be named message in triage reports.

This test property either passes or fails, which depends upon the evaluation of every assertion that shares its message. Different assertions in different parts of the code should have different message, but the same assertion should always have the same message even if it is moved to a different file.

details

Optional JSON. Optional additional information provided by the user to add context for assertion failures. The information that is logged will appear in the logs section of a triage report. Normally the values passed to details are evaluated at runtime.

The description of this parameter is identical for both lifecycle and assert.

The type of details is std::map<std::string, antithesis::ValueType> where antithesis::ValueType is a std::variant consisting of many common types, including a nested JSON type.

You can specify details using initialization syntax:

{
    {"name", "Bob"},
    {"number", 123.4}
}

You can also specify details using nested JSON, which requires the identifier antithesis::JSON:

{
    {"nested", antithesis::JSON{
                                {"a", "b"},
                                {"c", 1234}
                                }
    }
}