Handling External Dependencies

This is a detailed discussion of how to handle your system’s external 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 tutorial.

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.

Using the actual service

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 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:

Common external dependencies

Many of your open source external dependencies are likely to be available as docker images.

Messaging and queuing services

Database services

LLM services

Ollama

Using a mock service

Some external dependencies (e.g., AWS S3), can’t be containerized.

If you don’t own the service and the provider hasn’t made docker images available, you’ll have to use a pre-built mock, an API-compatible service, or a mock you write yourself.

List of pre-built mocks

This is a partial list provided for convenience, and does not imply any endorsement, except where clearly stated. If you’d like something added to this list please reach out on Discord.

AWS

Antithesis has been extensively tested with both Localstack and MinIO. We currently recommend MinIO for mocking S3, and Localstack for all other AWS services (as of Jan 2025), mostly because the free version of Localstack does not persist data to disk, which many of our customers require.

Localstack supports many services, including:

DynamoDB
S3
Lambda
CloudWatch
SSM
IAM
SQS

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

Stripe-Mock

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 speaking with one of our solutions engineers or reaching out on Discord.