{"id":3770,"library":"pytest-docker-tools","title":"pytest-docker-tools","description":"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.","status":"active","version":"3.1.9","language":"en","source_language":"en","source_url":"https://github.com/ibook-cn/pytest-docker-tools","tags":["pytest","docker","testing","integration testing","fixtures"],"install":[{"cmd":"pip install pytest-docker-tools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Essential peer dependency for a pytest plugin; tests are written using pytest framework.","package":"pytest","optional":false}],"imports":[{"note":"Used in conftest.py to define custom container fixtures.","symbol":"container","correct":"from pytest_docker_tools.factories import container"},{"note":"Used in conftest.py to define custom image fixtures.","symbol":"image","correct":"from pytest_docker_tools.factories import image"}],"quickstart":{"code":"# conftest.py\nimport pytest\nfrom pytest_docker_tools import container\n\n# Define a container using a public Nginx image\n# This fixture will be available to all tests.\nnginx_container = container(\n    image=\"nginx:alpine\",\n    ports={\"80/tcp\": None}, # Map internal port 80 to a random host port\n    # Add a readiness check for more robust tests (e.g., via wait_for_response)\n    # healthcheck_cmd=\"curl -f http://localhost/ || exit 1\",\n    # healthcheck_interval=1.0,\n    # healthcheck_timeout=5.0\n)\n\n# test_example.py\nimport requests\n\ndef test_nginx_is_reachable(nginx_container):\n    # The nginx_container fixture provides access to the running container instance\n    host, port = nginx_container.get_host_port(\"80/tcp\").split(':')\n    # The host might be '127.0.0.1' or 'localhost' depending on your Docker setup\n    url = f\"http://{host}:{port}\"\n    try:\n        response = requests.get(url, timeout=5)\n        assert response.status_code == 200\n        assert \"Welcome to nginx!\" in response.text\n    except requests.exceptions.ConnectionError as e:\n        pytest.fail(f\"Could not connect to Nginx container at {url}: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Update usage to unpack the tuple: `my_container, my_logs = container_factory(...)` or access `my_container = container_factory(...)[0]`.","message":"The `container_factory` fixture now returns a tuple `(container, logs)` instead of just the container object. Code expecting only the container object will break.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `host_ports={'80/tcp': 8080}` and `container_ports=['80/tcp']` with `ports={'80/tcp': 8080}`.","message":"The parameters `host_ports` and `container_ports` have been removed from `container` and `image` factories. Use the unified `ports` parameter instead.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update all references to the `container_logs` fixture to `get_container_logs`.","message":"The `container_logs` fixture has been renamed to `get_container_logs` for clarity.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"Python 3.7 support has been dropped. The library now requires Python 3.9 or higher.","severity":"breaking","affected_versions":">=3.0.0"},{"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).","message":"Tests will fail if the Docker daemon is not running or if there are permission issues accessing the Docker socket.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Containers may not be immediately 'ready' to serve requests even if they are running. Relying solely on container startup can lead to flaky tests.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}