uber-compose 2.1.3

docker compose testing env orchestrator

🚀 Uber-Compose — Lightweight Docker Compose Extension for Test Environments

🔧 Overview

Uber-Compose is a lightweight extension for managing test environments with Docker Compose. It simplifies infrastructure management for end-to-end (E2E) and integration testing by automatically provisioning services before tests begin and cleaning them up afterward.

It integrates seamlessly with the Vedro testing framework (https://vedro.io) via a dedicated plugin.

With Uber-Compose, you can define test environments, handle multiple docker-compose configurations, and focus entirely on your test scenarios — the infrastructure is managed for you.

---

✨ Key Features

• 🚀 Automated setup and teardown of Docker Compose services
• 🔌 Native plugin integration with Vedro (https://vedro.io)
• 🧩 Supports multiple docker-compose profiles
• 🛠️ Flexible command-line control
• 💻 Works in both local dev and CI/CD environments

---

📦 Installation

Install via pip:

pip install uber-compose

Or add to your requirements.txt:

uber-compose

---

🛠️ How to Use with Vedro

1. Setup tests container params and utils

See E2E Test Setup for configure test container for E2E testing

2. Enable the Plugin in vedro.cfg.py

from uber_compose import VedroUberCompose, ComposeConfig, Environment, Service, DEFAULT_ENV_DESCRIPTION

class Config(vedro.Config):
    class Plugins(vedro.Config.Plugins):
        class UberCompose(VedroUberCompose):
            enabled = True

            # Define Docker Compose services
            default_env = Environment(
                # named from docker-compose.yml
                Service("db"),
                # or simply
                "api",
                description=DEFAULT_ENV_DESCRIPTION
            )

            # Define Compose profiles
            compose_cfgs = {
                DEFAULT_COMPOSE: ComposeConfig(
                    compose_files="docker-compose.yml",
                ),
                "dev": ComposeConfig(
                    compose_files="docker-compose.yml:docker-compose.dev.yml",
                ),
            }

See Uber-Compose vedro config for fine tune uber-compose plugin in vedro.cfg.py

3. Run Your Tests

Uber-Compose will:

• Automatically start necessary services
• Ensure they are fully running before tests begin
• Restart conflicting services if configurations changed

Everything is handled for you!

Start the test environment:

# Start test container and Docker daemon
docker-compose up -d e2e-tests dockersock

# Run tests
docker-compose exec e2e-tests vedro run scenarios/

Or wrap it with Make like:

make up                    # Start containers
make e2e-run args='scenarios/'   # Run tests

Command Line Options

You can customize behavior dynamically:

• --uc-fr — Force restart of services
• --uc-v — Set logging verbosity level
• --uc-default / --uc-dev — Choose defined ComposeConfigs
• --uc-env — Filter tests by environment name/description

---

🎯 Environment-Specific Test Configurations

You can define custom environments for specific test scenarios and Uber-Compose will automatically provision the required services when running those tests.

Define Custom Environments

Create environment configurations that match your test requirements:

# envs.py
from uber_compose import Environment, Service

WEB_S3_MOCKMQ = Environment(
    Service("s3"),
    Service("mock_mq"),
    Service("cli"),
    Service("api")
)

MINIMAL_DB_ONLY = Environment(
    Service("database")
)

Use in Your Tests

Simply specify the environment in your test scenario:

# test.py
import vedro
from envs import WEB_S3_MOCKMQ

class Scenario(vedro.Scenario):
    subject = 'consume contest mq message without message'
    env = WEB_S3_MOCKMQ

    def when_message_consumed(self):
        # Your test logic here
        pass

Automatic Environment Management

Run your test file and the required environment will be set up automatically:

vedro run test_path.py

Uber-Compose will:

• ✅ Detect the custom environment specified in your test
• 🚀 Start only the required services (s3, mock_mq, cli, api)
• ⏱️ Wait for all services to be healthy before running the test
• 🧹 Clean up resources after test completion

This approach ensures each test gets exactly the infrastructure it needs, improving test isolation and reducing resource usage.

Filter Tests by Environment

You can filter which tests to run based on their environment using the --uc-env flag:

# Run only tests that use the default environment
vedro run scenarios/ --uc-env default

# Run only tests with a specific environment description
vedro run scenarios/ --uc-env "WEB_S3_MOCKMQ"

This is particularly useful when:

• 🎯 You want to run only tests for a specific infrastructure setup
• 🚀 Running focused test suites in CI/CD pipelines
• 🧪 Testing specific service configurations

Important: Tests without an explicit env parameter are considered to use the default environment and will match --uc-env default.

---

📚 Library Usage Details

• E2E Test Setup - Configure test container for E2E testing
• CLI Usage Guide - Guide for using CommonJsonCli with JSON log parsing
• X-Migration - Extended service initialization and migration commands

🛠️ Development Guide

• Release Tags & Versioning - Versioning and release tagging guide

---

✔️ Ideal For

• ✅ End-to-End (E2E) testing
• 🔗 Integration testing
• 🧪 Local development & reproducible CI pipelines
• 🎯 Structured tests with Vedro (https://vedro.io)

---

🤝 Contribute

We welcome pull requests, feature requests, and community feedback!

📍 Source Repository:
https://github.com/ko10ok/uber-compose

---

🧰 One Command. Fully Managed Environments.