{"id":3771,"library":"pytest-docker","title":"pytest-docker","description":"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.","status":"active","version":"3.2.5","language":"en","source_language":"en","source_url":"https://github.com/avast/pytest-docker","tags":["pytest","docker","testing","fixtures","docker-compose"],"install":[{"cmd":"pip install pytest-docker","lang":"bash","label":"Install `pytest-docker`"},{"cmd":"pip install pytest-docker 'docker-compose>=2.0.0; python_version >= \"3.10\"' 'docker-compose<2.0; python_version < \"3.10\"'","lang":"bash","label":"Install `pytest-docker` with explicit `docker-compose` library version"}],"dependencies":[{"reason":"Core testing framework, `pytest-docker` is a plugin for it.","package":"pytest","version":">=6.2.0,<9"},{"reason":"Python client for Docker Engine API.","package":"docker","version":"~=7.0"},{"reason":"Python library to interact with Docker Compose services. The specific version required depends on your Python interpreter: `pytest-docker` requires `docker-compose>=1.29.2,<2.0` for Python versions below 3.10, and `docker-compose>=2.0.0` for Python 3.10 and newer.","package":"docker-compose","version":"Conditional (>=1.29.2)"}],"imports":[{"note":"pytest automatically injects fixtures like `docker_compose`. Do not explicitly import them from `pytest_docker`.","symbol":"docker_compose","correct":"def test_something(docker_compose):\n    # Access services via docker_compose fixture\n    ..."},{"note":"pytest automatically injects fixtures like `docker_client`. Do not explicitly import them from `pytest_docker`.","symbol":"docker_client","correct":"def test_something(docker_client):\n    # Access Docker client via docker_client fixture\n    ..."},{"note":"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.","symbol":"docker_compose_file","correct":"import pytest\nfrom pathlib import Path\n\n@pytest.fixture(scope=\"session\")\ndef docker_compose_file():\n    return str(Path(__file__).parent / \"docker-compose.yml\")"},{"note":"Recommended for type hinting the `docker_compose` fixture for better IDE support and static analysis.","symbol":"Services","correct":"from pytest_docker.plugin import Services\n\ndef my_test_function(docker_compose: Services):\n    # Use for type hinting the docker_compose fixture\n    ..."}],"quickstart":{"code":"import pytest\nimport redis\nimport time\nfrom pathlib import Path\n\n# This fixture tells pytest-docker where to find docker-compose.yml.\n# Place this in your conftest.py or directly in your test file.\n@pytest.fixture(scope=\"session\")\ndef docker_compose_file():\n    # Assumes docker-compose.yml is in the same directory as this test file.\n    return str(Path(__file__).parent / \"docker-compose.yml\")\n\ndef test_redis_connection(docker_compose):\n    # The 'docker_compose' fixture automatically starts services from docker-compose.yml\n    # Get the host and exposed port for the 'redis' service\n    host, port = docker_compose.get_service_host_port(\"redis\", 6379)\n\n    # Poll until the Redis service is ready to accept connections\n    _redis_client = None\n    for _ in range(30): # Try for up to 30 seconds\n        try:\n            _redis_client = redis.Redis(host=host, port=port, decode_responses=True)\n            _redis_client.ping() # Check connection\n            break\n        except redis.exceptions.ConnectionError:\n            time.sleep(1)\n    else:\n        pytest.fail(\"Redis service not ready after 30 seconds\")\n\n    assert _redis_client is not None\n    _redis_client.set(\"mykey\", \"myvalue\")\n    assert _redis_client.get(\"mykey\") == \"myvalue\"\n    _redis_client.close()","lang":"python","description":"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:\n\n1.  **Create `docker-compose.yml`** (e.g., in the same directory as your test file):\n    ```yaml\n    services:\n      redis:\n        image: redis:latest\n        ports:\n          - \"6379:6379\"\n        healthcheck:\n          test: [\"CMD\", \"redis-cli\", \"ping\"]\n          interval: 1s\n          timeout: 3s\n          retries: 5\n    ```\n2.  **Create `test_redis.py`** with the code above.\n3.  **Run tests** from your terminal: `pytest`"},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or newer and ensure pytest is at a compatible version (e.g., v8+).","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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\"'`.","message":"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.","severity":"gotcha","affected_versions":"All versions (dependency constraint)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.2.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Prior to 3.2.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}