SDK reference
Antithesis offers SDKs in a number of popular languages:
These SDKs enable you to integrate Antithesis your development cycle, and also provide a means of configuring and controlling your Antithesis tests. All of our SDKs are designed to be able to run safely in production with minimal impact on your software’s performance.
To do this, the SDKs detect at startup time whether the program is running in the Antithesis Environment. If not, then their functions turn into no-ops, or log statements, or shims to appropriate standard library functions. SDK functions that turn into no-ops when run in production will still evaluate their arguments, so that antithesis_foo(function_with_vital_side_effects()) doesn’t become a bug.
However, if you have ultra-high performance software dependent on split-second timing, most of our SDKs provide ways to completely disable them at build time. The details of how this works differ a little bit from language to language, consult the language-specific SDK documentation for more information.
Our SDKs offer three main categories of functionality:
Test properties
Our SDKs allow you to define test properties – either in your test template or in your actual software. These properties resemble the programming assertions that you are likely familiar with, but often have specific applications in Antithesis testing, such as checking the reachability of your code and evaluating the quality of your tests. You can read more about how Antithesis evaluates these properties in the language-specific SDK documentation.
Properties you define using the SDKs will appear in your triage report and will be flagged as passing or failing in each of your test runs. Antithesis automatically collects detailed information based on properties you define and creates debugging artifacts at the moments when these assertions are evaluated.
Certain types of assertions in our SDK provide hints to our platform about which states should be explored in order to search for bugs.
Unlike many assertions libraries, failed Antithesis assertions do not cause your program to exit. This is useful in test, because we may be able to escalate an assertion failure into a more severe bug. It also reduces the friction to running the exact same code in test and production.
Randomness
Antithesis runs your tests in a deterministic simulation, so any random number generator (RNG) you consult will give the same sequence of answers in every test run. Since we wish to explore many possibilities over the course of each test, the Antithesis platform provides ways for your software – either your test template or your actual software – to request inputs that can be used in place of an RNG to make random decisions. The most straightforward way to do this is from the system random devices, which we override and replace with our own source of entropy. But the SDKs offer an alternative source that is both more convenient and more structured.
Use of SDK random functions is usually more convenient than opening and reading from system random devices. The SDK also offers higher-level, more “structured” random methods, for example the equivalent of the Python standard library’s random.choice(). These are not provided only for convenience, they also make it easier for the Antithesis Platform to learn what sorts of inputs to provide.
Suppose you have a randomized test template that runs one of three tests, a(), b(), and c(). Suppose that test c() is ineffective, and rarely or never provokes interesting behavior in your system. If you use an SDK random function to decide which test to run, then over time Antithesis will learn that inputs which result in c() running are less fruitful, and will not provide them as often. But it is much easier to learn this if you tell Antithesis that you are making a choice between three options, as opposed to requesting a 64-bit number and computing its value modulo 3.
A corollary of this is that you should never take inputs returned by SDK random functions and use them to seed your own RNG, or store them to make a decision later. Either one of these anti-patterns makes it harder for Antithesis to learn to control your software, and defeats the purpose of using the SDK.
Lifecycle
The SDKs also provide a way to signal to the Antithesis Environment when your tests transition from setup to runtime to cleanup.
It’s essential to signal to Antithesis when your system is fully initialized, and these functions provide an easy way to do so.
They’re also useful as a general source of information about the ordering of events during testing.
SDK Alternatives
If you cannot use our SDK, either due to policy, or because we have not yet produced an SDK in your language of choice, Antithesis offers a low-level fallback API.