Antithesis Java SDK

Overview

The Antithesis Java SDK offers classes for placing your Java code under test and using Antithesis functionality. It is available on Github and as a JAR on Maven Central.

The Antithesis Java SDK is intended for use with Java 8 or higher. Contact us if you want to use a different version.

Classes

The SDK provides three classes which each offer different functionality.

• The Assert class functions define test properties about your software or workload.
• The Random class functions request both structured and unstructured randomness from the Antithesis platform.
• The Lifecycle class functions inform the Antithesis environment that particular test phases or milestones have been reached.

Using the Java SDK

The basic workflow for using the Java SDK is:

1. Import the SDK classes into your Java program.

   E.g. import static com.antithesis.sdk.Assert.*;

2. Call SDK methods from your code. For example, use an assertion such as:

   always(some condition).

3. Build your Java project. Include the Antithesis SDK jar file as a dependency within your build system.

4. Deploy your build: either to Antithesis or into production.

SDK runtime behavior

The SDK is designed to have sensible fallback behavior that 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.

Methods in the Assert and Lifecycle classes have two modes for when your software is running outside Antithesis, including in production:

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 the default behavior.

2. Default with logging, which is the same as the above but logs output locally in a structured JSON format.

   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.

   E.g. set ANTITHESIS_SDK_LOCAL_OUTPUT=assertions_20240520.json at startup in the example above.

Methods in the Random class always fall back upon the java.util.Random class for entropy when run outside of Antithesis.

Further reading

• Tutorial
• Instrumentation
• Assert (reference)
• Lifecycle (reference)
• Random (reference)