antithesis.assertions

This module provides functions for basic assertions:
  • always
  • always_or_unreachable
  • sometimes
  • reachable
  • unreachable

This module allows you to define properties about your program or test template. It's part of the Antithesis Python SDK, which enables Python applications to integrate with the Antithesis platform.

These functions are no-ops with minimal performance overhead when called outside of the Antithesis environment. However, if the environment variable ANTITHESIS_SDK_LOCAL_OUTPUT is set, these functions will log to the file pointed to by that variable using a structured JSON format defined here. This allows you to make use of the Antithesis assertions package in your regular testing, or even in production. In particular, very few assertions frameworks offer a convenient way to define Sometimes assertions, but they can be quite useful even outside Antithesis.

Each function in this package takes a parameter called message, which is 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 the triage report. Different assertions in different parts of the code should have a different message, but the same assertion should always have the same message even if it is moved to a different file.

Each function also takes a parameter called details, which is a key-value map of optional additional information provided by the user to add context for assertion failures. The information logged will appear in the triage report, under the details section of the corresponding property. Normally the values passed to details are evaluated at runtime.

def always(condition: bool, message: str, details: Mapping[str, Any]) -> None:

Asserts that condition is true every time this function is called. This test property will be viewable in the “Antithesis SDK: Always” group of your triage report.

Arguments:
  • condition (bool): Indicates if the assertion is true
  • message (str): The unique message associated with the assertion
  • details (Mapping[str, Any]): Named details associated with the assertion
def always_or_unreachable(condition: bool, message: str, details: Mapping[str, Any]) -> None:

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

Arguments:
  • condition (bool): Indicates if the assertion is true
  • message (str): The unique message associated with the assertion
  • details (Mapping[str, Any]): Named details associated with the assertion
def sometimes(condition: bool, message: str, details: Mapping[str, Any]) -> None:

Asserts that condition is true at least one time that this function 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.

Arguments:
  • condition (bool): Indicates if the assertion is true
  • message (str): The unique message associated with the assertion
  • details (Mapping[str, Any]): Named details associated with the assertion
def reachable(message: str, details: Mapping[str, Any]) -> None:

Reachable asserts that a line of code is reached at least once. The corresponding test property will pass if this function 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.

Arguments:
  • condition (bool): Indicates if the assertion is true
  • message (str): The unique message associated with the assertion
  • details (Mapping[str, Any]): Named details associated with the assertion
def unreachable(message: str, details: Mapping[str, Any]) -> None:

Unreachable asserts that a line of code is never reached. The corresponding test property will fail if this function 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.

Arguments:
  • condition (bool): Indicates if the assertion is true
  • message (str): The unique message associated with the assertion
  • details (Mapping[str, Any]): Named details associated with the assertion
def assert_raw( condition: bool, message: str, details: Mapping[str, Any], loc_filename: str, loc_function: str, loc_class: str, loc_begin_line: int, loc_begin_column: int, hit: bool, must_hit: bool, assert_type: str, display_type: str, assert_id: str):

This is a low-level method designed to be used by third-party frameworks. Regular users of the assertions module should not call it.

This is primarily intended for use by adapters from other diagnostic tools that intend to output Antithesis-style assertions.

Be certain to provide an assertion catalog entry for each assertion issued with rawAssert(). Assertion catalog entries are also created using rawAssert(), by setting the value of the hit parameter to false.

Please refer to the general Antithesis documentation regarding the use of the Fallback SDK for additional information.

Arguments:
  • condition (bool): Runtime condition for the basic assertion
  • message (str): Unique message associated with a basic assertion
  • details (Mapping[str, Any]): Named details associated with a basic assertion at runtime
  • loc_filename (str): The name of the source file containing the called assertion
  • loc_function (str): The name of the function containing the called assertion
  • loc_class (str): The name of the class for the function containing the called assertion
  • loc_begin_line (int): The line number for the called assertion
  • loc_begin_column (int): The column number for the called assertion
  • hit (bool): True for runtime assertions, False if from an Assertion Catalog
  • must_hit (bool): True if assertion must be hit at runtime
  • assert_type (str): Logical handling type for a basic assertion
  • display_type (str): Human readable name for a basic assertion
  • assert_id (str): Unique id for the basic assertion