Skip to main content

🚀 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

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

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.1.0
File Size Uploaded Provenance Actions
uber_compose-3.1.0.tar.gz 91.5 kB Without provenance Details for uber_compose-3.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 204.1 kB

Release files / uber_compose-3.1.0.tar.gz

Download URL uber_compose-3.1.0.tar.gz
Size 91.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8b4d41f72d213036504bcbd3144f65f0b77501c2af4d4d38a34ccdc3a6bba8fa
BLAKE2b-256 checksum
How to use checksums
8062ace314963152f2b9e029c321c66fa125550ab63db8ca14fb783b4487a1f6
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.1.0-py3-none-any.whl

Download URL uber_compose-3.1.0-py3-none-any.whl
Size 112.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ecec701dd4777428a7db4cec4e6e59c81c2dc3043f49e61d4b66c57b44a3a315
BLAKE2b-256 checksum
How to use checksums
2eed8e4f10d901af8411981ed3c9650caf5877d72b80ecf7c400ce99fcd1e39d
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.1.0

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

3.1.0 This release

2 release files No provenance

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