pytest-docker-compose 3.2.1

Waiting for Services to Come Online

The fixtures called 'scope'_scoped_container_getter 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 an example of a fixture called wait_for_api that waits for an HTTP service to come online before a test called test_read_and_write can run.

import pytest
import requests
from urllib.parse import urljoin
from urllib3.util.retry import Retry
from requests.adapters import HTTPAdapter

pytest_plugins = ["docker_compose"]

# Invoking this fixture: 'function_scoped_container_getter' starts all services
@pytest.fixture(scope="function")
def wait_for_api(function_scoped_container_getter):
    """Wait for the api from my_api_service to become responsive"""
    request_session = requests.Session()
    retries = Retry(total=5,
                    backoff_factor=0.1,
                    status_forcelist=[500, 502, 503, 504])
    request_session.mount('http://', HTTPAdapter(max_retries=retries))

    service = function_scoped_container_getter.get("my_api_service").network_info[0]
    api_url = "http://%s:%s/" % (service.hostname, service.host_port)
    assert request_session.get(api_url)
    return request_session, api_url


def test_read_and_write(wait_for_api):
    """The Api is now verified good to go and tests can interact with it"""
    request_session, api_url = wait_for_api
    data_string = 'some_data'
    request_session.put('%sitems/2?data_string=%s' % (api_url, data_string))
    item = request_session.get(urljoin(api_url, 'items/2')).json()
    assert item['data'] == data_string
    request_session.delete(urljoin(api_url, 'items/2'))

Use wider scoped fixtures

The function_scoped_container_getter fixture uses “function” scope, meaning that all of the containers are torn down after each individual test.

This is done so that every test gets to run in a “clean” environment. However, this can potentially make a test suite take a very long time to complete.

There are two options to make containers persist beyond a single test. The best way is to use the fixtures that are explicitly scoped to different scopes. There are three additional fixtures for this purpose: class_scoped_container_getter, module_scoped_container_getter and session_scoped_container_getter. Notice that you need to be careful when using these! There are two main caveats to keep in mind:

1. Manage your scope correctly, using ‘module’ scope and ‘function’ scope in one single file will throw an error! This is because the module scoped fixture will spin up the containers and then the function scoped fixture will try to spin up the containers again. Docker compose does not allow you to spin up containers twice.

2. Clean up your environment after each test. Because the containers are not restarted their environments can carry the information from previous tests. Therefore you need to be very carefull when designing your tests such that they leave the containers in the same state that it started in or you might run into difficult to understand behaviour.

A second method to make containers persist beyond a single test is to supply the –use-running-containers flag to pytest like so:

pytest --use-running-containers

With this flag, pytest-docker-compose checks that all containers are running during the project creation. If they are not running a warning is given and they are spun up anyways. They are then used for all the tests and NOT TORE DOWN afterwards.

This mode is best used in combination with the ‘–docker-compose-no-build’ flag since the newly build containers won’t be used anyways. like so:

pytest --docker-compose-no-build --use-running-containers

It is off course possible to add these options to pytest.ini.

Notice that for this mode the scoping of the fixtures becomes less important since the containers are fully persistent throughout all tests. I only recommend using this if your network takes excessively long to spin up/tear down. It should really be a last resort and you should probably look into speeding up your network instead of using this.