Skip to main content

Manages Docker containers during your integration tests

Project description

This package contains a pytest plugin for integrating Docker Compose into your automated integration tests.

Given a path to a docker-compose.yml file, it will automatically build the project at the start of the test run, bring the containers up before each test starts, and tear them down after each test ends.


Make sure you have Docker installed.

This plugin has been tested against the following software:

  • Python 3.6
  • pytest 3.4 and 3.5.


This plugin is not compatible with Python 2.


Install the plugin using pip:

> pip install pytest-docker-compose


For performance reasons, the plugin is not enabled by default, so you must activate it manually in the tests that use it:

pytest_plugins = ["docker_compose"]

See Installing and Using Plugins for more information.

To interact with Docker containers in your tests, use the following fixtures:


A list of pytest_docker_compose.NetworkInfo objects for each container, grouped by service name.

This information can be used to configure API clients and other objects that will connect to services exposed by the Docker containers in your tests.

NetworkInfo is a container with the following fields:

  • container_port: The port (and usually also protocol name) exposed internally to the container. You can use this value to find the correct port for your test, when the container exposes multiple ports.
  • hostname: The hostname (usually “localhost”) to use when connecting to the service from the host.
  • host_port: The port number to use when connecting to the service from the host.


Unless you need to interface directly with Docker primitives, this is the correct fixture to use in your tests.

A list of the Docker compose.container.Container objects running during the test.
The compose.project.Project object that the containers are built from. This fixture is generally only used internally by the plugin.

Waiting for Services to Come Online

The fixture will wait until every container is up before handing control over to the test.

However, just because a container is up does not mean that the services running on it are ready to accept incoming requests yet!

If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), make sure that your fixtures account for this.

Here’s a simple example of a fixture that waits for an HTTP service to come online before starting each test.

import pytest
import typing
from pytest_docker_compose import NetworkInfo
from time import sleep, time

from my_app import ApiClient

pytest_plugins = ["docker_compose"]

def fixture_api_client(
        docker_network_info: typing.Dict[str, typing.List[NetworkInfo]],
) -> ApiClient:
    # ``docker_network_info`` is grouped by service name.
    service = docker_network_info["my_api_service"][0]

    # Create an instance of our custom application's API client.
    api_client = ApiClient(

    # Wait for the HTTP service to be ready.
    start = time()
    timeout = 5

    for name, network_info in docker_network_info.items():
        while True:
            if time() - start >= timeout:
                raise RuntimeError(
                    f"Unable to start all container services "
                    "within {timeout} seconds.",

                if api_client.health_check()["status"] == "ok":
            except (ConnectionError, KeyError):


    # HTTP service is up and listening for requests.
    return api_client

# Tests can then interact with the API client directly.
def test_frog_blast_the_vent_core(api_client: ApiClient):
    assert api_client.frog_blast_the_vent_core() == {
        "status": "I'm out of ammo!",

Running Integration Tests

Use pytest to run your tests as normal:


By default, this will look for a docker-compose.yml file in the current working directory. You can specify a different file via the --docker-compose option:

pytest --docker-compose=/path/to/docker-compose.yml


Alternatively, you can specify this option in your pytest.ini file:

addopts = --docker-compose=/path/to/docker-compose.yml

The option will be ignored for tests that do not use this plugin.

See Configuration Options for more information on using configuration files to modify pytest behavior.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest-docker-compose-1.0.1.tar.gz (9.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page