Creating test templates

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

See test commands for details of available test commands.

Creating a test template

A test template is a directory that lives under /opt/antithesis/test/v1/ and contains scripts called test commands. For convenience, we sometimes refer to /opt/antithesis/test/v1/ as the “test directory”.

Here’s an example file structure:

/opt/antithesis/test/v1/               ← test directory
├── main/                              ← a test template
    ├── first_setup.py
    ├── parallel_driver_produce.py
    ├── parallel_driver_consume.py
    ├── serial_driver_compact.sh
    ├── anytime_health.py
    ├── eventually_verify.py
    ├── finally_consistency.sh
    ├── helper_utils.py                ← ignored by Antithesis (helper_ prefix)
    └── helper_modules/                ← ignored by Antithesis (helper_ prefix)
        └── kafka_client.py

You can place your test templates under /opt/antithesis/test/v1/ inside any of your containers, but we recommend placing it in a dedicated container rather than in your system containers.

Multiple containers can also share a test template, see below.

Any container with test templates must be kept running (e.g., via sleep infinity in the entrypoint). Do not use a test command as the container entrypoint.

Using multiple test templates

You can add multiple test templates under /opt/antithesis/test/v1/. By placing multiple test templates in the test directory, you can use different testing strategies during a single Antithesis run.

Here’s an example:

/opt/antithesis/test/v1/
├── basic/                            ← simple producer/consumer tests
│   ├── first_create_topic.py
│   ├── parallel_driver_produce.py
│   └── parallel_driver_consume.py
├── transactional/                    ← transaction-focused tests
│   ├── first_setup_tx.py
│   ├── parallel_driver_tx_write.py
│   └── finally_tx_verify.py
└── stress/                           ← high-throughput stress test
    └── singleton_driver_load.py

Antithesis selects exactly one template per execution history. Test commands in basic/ will never run alongside test commands in transactional/ or stress/.

This means all commands in a single test template should be compatible with each other, but you can include incompatible commands in different test templates.

If containers client-a and client-b both have a directory called /opt/antithesis/test/v1/main/, Antithesis treats both instances of main as a single test template with commands spread across both containers. Each command runs inside the container where it is defined.

Helper files

Subdirectories and files with a helper_ prefix in their name are ignored by Antithesis. Use this prefix for shared libraries, utility modules, and configuration files that your test commands require.

Creating a test template

Using multiple test templates

Sharing test templates across multiple containers

Helper files