pytest-docker

3.2.5 · active · verified Sat Apr 11

pytest-docker provides simple pytest fixtures for testing applications that rely on Docker or Docker Compose services. It simplifies the setup and teardown of Docker containers or multi-container applications (defined via `docker-compose.yml`) for integration tests, automatically managing their lifecycle. The current version is 3.2.5, and it maintains an active release cadence with frequent updates.

Warnings

breaking Version 3.0.0 introduced a breaking change by dropping support for Python 3.6 and 3.7. Python 3.8+ is now required, alongside compatibility with pytest v8.
Fix: Upgrade your Python environment to 3.8 or newer and ensure pytest is at a compatible version (e.g., v8+).
gotcha The `docker-compose` Python library dependency version is conditional on your Python interpreter. For Python versions below 3.10, `docker-compose` version 1.x is required. For Python 3.10 and newer, `docker-compose` version 2.x is required. Incorrect versions can lead to `ImportError` or unexpected behavior.
Fix: Ensure the correct `docker-compose` library version is installed for your Python environment. For example, `pip install 'docker-compose>=2.0.0; python_version >= "3.10"'` or `pip install 'docker-compose<2.0; python_version < "3.10"'`.
gotcha As of v3.2.5, the default `docker_setup_command` for `docker_compose` now includes `--wait`. This command blocks until all services are 'healthy' according to their `healthcheck` definitions. This can significantly increase service startup time during tests if healthchecks are slow or improperly configured.
Fix: Review your `docker-compose.yml` to ensure services have appropriate and efficient `healthcheck` configurations. If strict waiting is not desired, you may need to override the `docker_setup_command` fixture to remove the `--wait` flag.
gotcha The `docker_setup_command` fixture was fixed in v3.2.1 to correctly reference `docker_setup`. Users who might have manually overridden `docker_setup_command` in older versions should verify their fixture names and implementations for compatibility.
Fix: Check any custom `docker_setup_command` or `docker_setup` fixtures in your `conftest.py`. Ensure they align with the library's expected naming and behavior, especially if you encountered issues with custom setup commands.
gotcha The Docker daemon must be running and accessible for `pytest-docker` to function. This library does not manage the Docker daemon itself, only the containers/services it orchestrates.
Fix: Verify that Docker Desktop or your Docker daemon is running and properly configured before executing tests. Use `docker ps` in your terminal to confirm Docker is operational.

Install

pip install pytest-docker Install `pytest-docker`
pip install pytest-docker 'docker-compose>=2.0.0; python_version >= "3.10"' 'docker-compose<2.0; python_version < "3.10"' Install `pytest-docker` with explicit `docker-compose` library version

Imports

docker_compose
```
def test_something(docker_compose):
    # Access services via docker_compose fixture
    ...
```
pytest automatically injects fixtures like `docker_compose`. Do not explicitly import them from `pytest_docker`.
docker_client
```
def test_something(docker_client):
    # Access Docker client via docker_client fixture
    ...
```
pytest automatically injects fixtures like `docker_client`. Do not explicitly import them from `pytest_docker`.
docker_compose_file
```
import pytest
from pathlib import Path

@pytest.fixture(scope="session")
def docker_compose_file():
    return str(Path(__file__).parent / "docker-compose.yml")
```
This fixture defines the path to your `docker-compose.yml` file. It should be defined in `conftest.py` or a test file to specify the location.

Services

from pytest_docker.plugin import Services

def my_test_function(docker_compose: Services):
    # Use for type hinting the docker_compose fixture
    ...

Recommended for type hinting the `docker_compose` fixture for better IDE support and static analysis.

Quickstart

To use `pytest-docker`, define your Docker Compose services in a `docker-compose.yml` file and then use the `docker_compose` fixture in your tests. You must define a `docker_compose_file` fixture to point to your compose file. This example uses a Redis service: 1. **Create `docker-compose.yml`** (e.g., in the same directory as your test file): ```yaml services: redis: image: redis:latest ports: - "6379:6379" healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 1s timeout: 3s retries: 5 ``` 2. **Create `test_redis.py`** with the code above. 3. **Run tests** from your terminal: `pytest`

import pytest
import redis
import time
from pathlib import Path

# This fixture tells pytest-docker where to find docker-compose.yml.
# Place this in your conftest.py or directly in your test file.
@pytest.fixture(scope="session")
def docker_compose_file():
    # Assumes docker-compose.yml is in the same directory as this test file.
    return str(Path(__file__).parent / "docker-compose.yml")

def test_redis_connection(docker_compose):
    # The 'docker_compose' fixture automatically starts services from docker-compose.yml
    # Get the host and exposed port for the 'redis' service
    host, port = docker_compose.get_service_host_port("redis", 6379)

    # Poll until the Redis service is ready to accept connections
    _redis_client = None
    for _ in range(30): # Try for up to 30 seconds
        try:
            _redis_client = redis.Redis(host=host, port=port, decode_responses=True)
            _redis_client.ping() # Check connection
            break
        except redis.exceptions.ConnectionError:
            time.sleep(1)
    else:
        pytest.fail("Redis service not ready after 30 seconds")

    assert _redis_client is not None
    _redis_client.set("mykey", "myvalue")
    assert _redis_client.get("mykey") == "myvalue"
    _redis_client.close()

view raw JSON →