Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

🚀 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-ju — Bring up the environment without running any tests
  • --uc-default / --uc-dev — Choose between defined ComposeConfigs
  • --uc-env — Filter tests by environment name/description
  • --uc-mt — Enable parallel scenario execution (worker processes)
  • --uc-workers-per-env N / --uc-wpe N — Override workers per env for this run

For parallel runs see Parallel Runs by Use Case — it shows which config and which flag to use for each scenario.


🎯 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
  • Lifecycle Hooks - Register callbacks that run after the environment is up
  • Parallel Runs by Use Case - When to pass --uc-mt, which ComposeConfig to use, workers per env, env rotation and per-service env access

🛠️ Development 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.

Metadata

Release files for uber-compose 3.0.0a8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uber-compose 3.0.0a8
File Size Uploaded Provenance Actions
uber_compose-3.0.0a8.tar.gz 78.5 kB Without provenance Details for uber_compose-3.0.0a8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uber-compose 3.0.0a8
File Interpreter ABI Platform Actions
uber_compose-3.0.0a8-py3-none-any.whl Python 3 none any Details for uber_compose-3.0.0a8-py3-none-any.whl

Total release size: 175.8 kB

Release files / uber_compose-3.0.0a8.tar.gz

Download URL uber_compose-3.0.0a8.tar.gz
Size 78.5 kB
Tags Source
SHA-256 checksum
How to use checksums
350da9d9b04036efc0b188d17b7430284cdd95b1be6af391a28af50706b2c382
BLAKE2b-256 checksum
How to use checksums
39674db45ce097f2ffba67afe73a046e0fce4323f306810c7d35e45bb1856550
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / uber_compose-3.0.0a8-py3-none-any.whl

Download URL uber_compose-3.0.0a8-py3-none-any.whl
Size 97.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3919ffc923c0d4868345af2ee7dee323edad1ab14394771997183e6a3bcead11
BLAKE2b-256 checksum
How to use checksums
4dff00e2bee78ff173fe2d0071c85a5c863fa4ba7e2cacc7132584e75e5adf71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for uber-compose 3.0.0a8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page