Handling External Dependencies

This is a detailed discussion of how to handle your system’s dependencies for testing in Antithesis. Remember, testing happens in a hermetic testing environment with no internet access, because your software’s always wanted its own little Faraday cage.

For an overview of this topic, please read the setup guide.

Approaches

Each of your software’s dependencies can be provided either as:

An actual, containerized service, just like you’d use in production.
A mock of the service, which could be pre-built (e.g., Localstack), or something you write yourself. You’ll use this approach for external dependencies that can’t be containerized (e.g. AWS S3), or when the service provider hasn’t made docker images available.

Dependencies available off-the-shelf

This directory lists containerized open-source services that can simply be included in your Docker Compose file, and pre-built, containerized mocks.

If you’d like something added to this directory please reach out on Discord.

AWS Mocks

Antithesis has been extensively tested with both Localstack and MinIO. As of June 2025, we recommend using MinIO in place of S3 when you test in Antithesis, and mocking all other AWS services with Localstack, mostly because the free version of Localstack does not persist data to disk, which many customers require. We provide sample docker-compose.yaml blocks for both of these below.

Localstack supports many services, including:

DynamoDB
S3
Lambda
CloudWatch
SSM
IAM
SQS

Other pre-built mocks for AWS include:

Azure Mocks

GCP Mocks

Messaging and queuing services

Database services

LLM services

Ollama

Payment service mocks

Stripe-Mock

Docker code for including dependencies

For actual services

If the dependency is something you own, such as a private Docker image, you can upload it to our private registry. Whether the image is private or publicly available on a registry like Docker Hub, you should define it as a service in your Docker Compose file:

version: '3.8'

services:
  service.mysoftware:
    image: mysoftware:latest
    container_name: mysoftware
    hostname: mysoftware
    depends_on: 
      - infra.postgres

  infra.postgres: 
    image: docker.io/postgres:16
    container_name: postgres
    hostname: postgres
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s

volumes:
  postgres_data:

Localstack

Add Localstack to docker-compose.yaml:

infra.localstack:
  image: localstack/localstack:3.5.0
  container_name: localstack
  hostname: localstack
  environment:
    SERVICES: s3
    DEBUG: 0
    LS_LOG: warn
    SKIP_SSL_CERT_DOWNLOAD: 1
    DISABLE_EVENTS: 1
    LOCALSTACK_HOST: localstack
    DEFAULT_REGION: us-east-1
  volumes:
    - /var/lib/localstack:/var/lib/localstack
    - /var/run/docker.sock:/var/run/docker.sock

MinIO

MinIO is S3-compatible blob storage (not a mock).

To add MinIO to docker-compose.yaml:

infra.minio:
  container_name: minio
  hostname: minio
  image: quay.io/minio/minio
  command: server /data --console-address ":9001"
  post_start:
    - user: "root"
      command: "mkdir -p /data/primary"
  ports:
    - "9000:9000"
    - "9001:9001"
  volumes:
    - minio_data:/data
  environment:
    - MINIO_ROOT_USER=minio
    - MINIO_ROOT_PASSWORD=minio-secret
    - MINIO_DEFAULT_BUCKETS=primary

Writing a mock yourself

Several tools are available to assist with writing your own mocks, if nothing in the provider’s ecosystem meets your needs.

This is a partial list, provided only for convenience, with no endorsement implied:

If you’d like to explore this approach, we suggest emailing us at support@antithesis.com or reaching out on Discord.