Test Composer Basics

This page explains how to create test templates for Antithesis, and how Antithesis recognizes and runs them.

The quickest way to write your first test template is described in this section of Getting Started guide. If you’re looking for a list of available test commands, you should consult the Test Composer reference.

Structuring test templates

Antithesis uses an opinionated framework for creating test templates, in the form of a set of naming conventions that enable Antithesis to detect and run your tests. You can also adapt existing tests or workloads for use as test templates instead of writing a test template from scratch (and many users do).

• A test directory is a subdirectory of /opt/antithesis/test/v1 in any of your containers.
• A test command is a specially-named executable (e.g. a shell script, python script, or executable binary) nested directly under the test directory.

The simplest possible test template in Antithesis consists of a single test directory containing a single test command, but you can have multiple test directories and multiple test commands per directory.

We strongly suggest putting test directories in a standalone container, to simulate a client – your “test container”. If you do this, the test container must be kept running, for instance by using sleep infinity. Do not use a test command as the entry point for the test container.

Test commands will run inside the container where they’re defined.

Test directories

/opt/antithesis/test/v1/<test_name>

A test directory is a directory in a container that represents a collection of test commands that are compatible with one another. In any particular branch of the Antithesis multiverse, test commands will all be selected from the same test directory. If test directories with the same name appear in multiple containers, they will be treated as belonging to the same test, even if they define different test commands.

<test_name> can be any valid directory name.

Test commands

<test_name>/<prefix>_<command>

A test command is an executable for the Test Composer to run. It can be a binary or script and must have an appropriate shebang in the first line, e.g. #!/usr/bin/env bash

It may have any or no extension, but must be marked executable by the container’s default user. It will typically call the APIs of the software under test in order to change the state of the system, check properties, or both.

<prefix> specifies the type of test command. See options in the reference docs. <command> can be any valid unix filename.

Starting your tests

Before running any tests, Antithesis initializes your software and its dependencies. Getting started describes this process in detail.

Once your system is up and running, it should emit a SetupComplete message using our SDKs. This message tells Antithesis to start the Test Composer and begin injecting faults.

The SetupComplete message should therefore not be part of a test command, though it’s fine for it to exist in the same container, for example, as part of the container’s entry point.

Adapting existing tests

If you want to use an existing test or workload in Antithesis, whether it’s an existing integration test or an advanced, well-developed distributed systems workload, you can run it in the Test Composer simply by making it a singleton_driver test command in a test directory as described above. If you run into any problems with this approach, please get in touch on Discord.

Checking your setup locally

Because the Test Composer expects to run inside Antithesis’ deterministic testing environment, it depends on assumptions about the multiverse and container orchestration that only hold in Antithesis.

If you’d like to check your setup locally to ensure that your test templates will work before deploying them to Antithesis, please read our guide to local development.