Registry / testing / pytest-docker-tools

pytest-docker-tools

library3.1.10pypypi✓ verified 25d ago

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.

testing devops

pip install pytest-docker-tools

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-DOCKER-TOOL

pytest-docker-tools

testingpythonv3.1.10

Install

3.4s avg

Import

833ms

Disk

35MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.1.10 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.850s · 35.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.4s · import 0.816s · 36MB

35MB installed

● package 35MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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}")

Debug

Known issues

breakingThe `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]`.

affects: >=3.0.0

breakingThe 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}`.

affects: >=3.0.0

breakingThe `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`.

affects: >=3.0.0

breakingPython 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.

affects: >=3.0.0

gotchaTests 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).

affects: All

gotchaContainers 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.

affects: All

Errors

Common errors & fixes

pytest fixture 'container' not found

The `pytest-docker-tools` plugin is not correctly registered with pytest, typically because `pytest_plugins = ['pytest_docker_tools']` is missing or misspelled in your `conftest.py` file, or the `conftest.py` is not in a location discoverable by pytest.

fix

Create or update your `conftest.py` file in your test suite's root directory with the line: `pytest_plugins = ['pytest_docker_tools']`.

AttributeError: 'Container' object has no attribute 'wait_for_condition'

Users often expect a `wait_for_condition` method directly on the `container` fixture, possibly confusing it with other `wait_for_output` or specific waiting functions, or a deprecated API.

fix

Use the more specific `container.wait_for_output(..., condition=...)` for log conditions, `container.wait_for_port()` for port availability, or other provided waiting utilities like `wait_for_ok`.

Error response from daemon: dockerfile_path

This error originates from the Docker daemon when `pytest-docker-tools` attempts to build a custom image, indicating a problem with the specified `dockerfile_path` or the build context (e.g., incorrect path, missing Dockerfile, or syntax error within the Dockerfile itself).

fix

Verify the `dockerfile_path` and `context` provided to your `image_source` or `ImageBuilder` definition. Ensure the Dockerfile exists at the specified path relative to the context and that its content is valid Dockerfile syntax.

docker.errors.APIError: 500 Server Error for http+docker://localhost/v1.XX/containers/...: Internal Server Error (...)

This indicates a generic communication or internal issue with the Docker daemon, often due to the Docker service not running, insufficient user permissions to access the Docker socket, or a corrupted Docker installation.

fix

Ensure the Docker daemon is actively running on your system. Check your user's permissions to access the Docker socket (e.g., add your user to the `docker` group on Linux). Restart the Docker daemon or your system if necessary.

Upgrade

Version history

3.1.10latest on PyPI · released Jul 21, 2026

Audit

Dependencies

pytestrequiredEssential peer dependency for a pytest plugin; tests are written using pytest framework.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Jc2k/pytest-docker-tools ↗

packagehttps://pypi.org/project/pytest-docker-tools/ ↗