pytest-docker-tools

3.1.9 · active · verified Sat Apr 11

pytest-docker-tools is a pytest plugin that simplifies writing integration tests with Docker containers. It provides fixtures for managing Docker images and containers, allowing tests to easily spin up and tear down isolated environments. As of its latest version 3.1.9, it's actively maintained with a regular release cadence, primarily driven by new features, bug fixes, and compatibility updates.

Warnings

breaking The `container_factory` fixture now returns a tuple `(container, logs)` instead of just the container object. Code expecting only the container object will break.
Fix: Update usage to unpack the tuple: `my_container, my_logs = container_factory(...)` or access `my_container = container_factory(...)[0]`.
breaking The parameters `host_ports` and `container_ports` have been removed from `container` and `image` factories. Use the unified `ports` parameter instead.
Fix: Replace `host_ports={'80/tcp': 8080}` and `container_ports=['80/tcp']` with `ports={'80/tcp': 8080}`.
breaking The `container_logs` fixture has been renamed to `get_container_logs` for clarity.
Fix: Update all references to the `container_logs` fixture to `get_container_logs`.
breaking Python 3.7 support has been dropped. The library now requires Python 3.9 or higher.
Fix: Upgrade your Python environment to 3.9 or newer.
gotcha Tests will fail if the Docker daemon is not running or if there are permission issues accessing the Docker socket.
Fix: Ensure Docker Desktop or Docker Engine is running and your user has the necessary permissions to interact with the Docker daemon (e.g., by being in the `docker` group).
gotcha Containers may not be immediately 'ready' to serve requests even if they are running. Relying solely on container startup can lead to flaky tests.
Fix: Implement robust readiness checks using parameters like `healthcheck_cmd`, `wait_for_response`, `wait_for_log`, or custom code within the fixture to poll the container until it's actually ready.

Install

pip install pytest-docker-tools Install stable version

Imports

container
```
from pytest_docker_tools.factories import container
```
Used in conftest.py to define custom container fixtures.
image
```
from pytest_docker_tools.factories import image
```
Used in conftest.py to define custom image fixtures.

Quickstart

This quickstart defines an `nginx_container` fixture in `conftest.py` that uses the `nginx:alpine` Docker image, mapping port 80. A test then uses this fixture to assert that the Nginx server is reachable and responds with the expected content. This demonstrates defining a container and using it in a test.

# conftest.py
import pytest
from pytest_docker_tools import container

# Define a container using a public Nginx image
# This fixture will be available to all tests.
nginx_container = container(
    image="nginx:alpine",
    ports={"80/tcp": None}, # Map internal port 80 to a random host port
    # Add a readiness check for more robust tests (e.g., via wait_for_response)
    # healthcheck_cmd="curl -f http://localhost/ || exit 1",
    # healthcheck_interval=1.0,
    # healthcheck_timeout=5.0
)

# test_example.py
import requests

def test_nginx_is_reachable(nginx_container):
    # The nginx_container fixture provides access to the running container instance
    host, port = nginx_container.get_host_port("80/tcp").split(':')
    # The host might be '127.0.0.1' or 'localhost' depending on your Docker setup
    url = f"http://{host}:{port}"
    try:
        response = requests.get(url, timeout=5)
        assert response.status_code == 200
        assert "Welcome to nginx!" in response.text
    except requests.exceptions.ConnectionError as e:
        pytest.fail(f"Could not connect to Nginx container at {url}: {e}")

view raw JSON →