Building your software when using the SDK

When you use the Antithesis Java SDK, you may want to adjust your build/deploy process as follows:

1. Enable assertion cataloging and coverage instrumentation for your software.
2. Start your JARs in a specific way.

Enable assertion cataloging

Assertion cataloging is required when using SDK assertions.

Place directories, files, or symlinks to the code you want cataloged in the directory /opt/antithesis/catalog/ within your container image. Generally, this means any .jar and/or .war files.

Antithesis will recursively instrument and catalog all the code in this directory, including any JARs or WARs. Instrumentation and cataloging for separate .class files is not currently supported.

Enable coverage instrumentation

Antithesis can automatically instrument compiled Java code by means of bytecode weaving. No changes to your source code or build system are required.

Instrumentation is enabled the same way as assertion cataloging, so if you enabled assertion cataloging, no additional steps are required.

Just remember Antithesis will follow only one symlink deep into each item in /opt/antithesis/catalog/.

Example cataloging directory:

> ln -s /usr/share/my_app /opt/antithesis/catalog 

> ls -lAh /opt/antithesis/catalog
lrwxrwxrwx  1 me users 4 Apr  8 17:32 /opt/antithesis/catalog -> /usr/share/my_app

> ls -lAh /opt/antithesis/catalog/
-rwxr-xr-x  1 me users  20K Apr  8 17:33 dotnet_file.dll
lrwxrwxrwx  1 me users 27 Apr  8 17:52 more_files -> /opt/my_project/java_files 
-rwxr-xr-x  1 me users  10K Apr  8 17:33 python_script.py

> ls -lA /opt/antithesis/catalog/more_files/
-rw-r--r--  1 me users  16K Apr  8 17:51 main.jar
lrwxrwxrwx  1 me users  16K Apr  8 17:51 my_other.jar -> /some/other/place.jar

Based on the example above, the following files would be instrumented:

• dotnet_file.dll
• python_script.py
• main.jar

Ignored files:

• my_other.jar - this will be ignored as we already encountered one symlink when traversing down from opt/antithesis/catalog/more_files.

If you need help with instrumentation, contact us at support@antithesis.com or ask on our Discord.

Enable symbolization

Antithesis automatically gathers the symbol information from your code. You don’t need to separately provide symbol files.

Starting your JARs

When running assertion cataloging and instrumentation, Antithesis createa additional dependencies for the application, and inject the dependency JARs at the same path as the main application JAR, so you will need to add that folder to your classpath.

For example, if you are starting the app in /opt/app/bin/sample_app.jar, then we will require /opt/app/bin/* to be on the classpath.

This means invoking your app JAR like:

java -ea -cp "/opt/app/bin/*" com.your_org.sample_app.controller.Method

This ensures that you are scanning the classpath that includes the Antithesis-injected dependencies, as well as invoking the main program method.

The following invocation will not work:

java -jar /opt/app/bin/sample_app.jar