pytest-docker-compose-v2 0.2.0__tar.gz → 0.3.0__tar.gz

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/.github/workflows/release.yaml

@@ -16,9 +16,9 @@ jobs:
       id-token: write
     steps:
     - name: Check out repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v7
     - name: Set up uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@v10.2.0
       with:
         enable-cache: true
         python-version: '3.13'
@@ -28,7 +28,7 @@ jobs:
     - name: Run tests
       run: uv run pytest
     - name: Create GitHub release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v3
       with:
         name: Release ${{ github.ref }}
         tag_name: ${{ github.ref }}

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/.github/workflows/test.yaml

@@ -18,14 +18,14 @@ jobs:
         pytest-version: ['7', '8', '9']
     steps:
     - name: Check out repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v7
       # needed because we use git describe to get a bumpver compatible GITHASH containing version
       # alternatively can look at using HEXHASH instead. Note that these are purposefully not
       # documented in the bumpver project, see issues/PRs for more info.
       # with:
       #   fetch-depth: 0
     - name: Set up uv
-      uses: astral-sh/setup-uv@v7
+      uses: astral-sh/setup-uv@v10.2.0
       with:
         enable-cache: true
         python-version: ${{ matrix.python-version }}
@@ -34,7 +34,9 @@ jobs:
     - name: Install pytest ${{ matrix.pytest-version }}
       run: uv pip install "pytest>=${{ matrix.pytest-version }},<$(( ${{ matrix.pytest-version }} + 1 ))"
     - name: Run tests
-      run: uv run pytest
+      run: uv run --no-sync pytest
+    - name: Run healthcheck wait tests
+      run: uv run --no-sync pytest -m wait_for_healthcheck --docker-compose ./tests/pytest_docker_compose_tests/my_network --docker-compose-wait
     # NOTE: publishing to test repository is disabled until I figure out a way to do it reliably
     # this means that we need to avoid version clashes as well as local versions
     # see: https://github.com/pypa/packaging.python.org/issues/804

pytest_docker_compose_v2-0.3.0/Justfile

@@ -0,0 +1,76 @@
+set shell := ["bash", "-euo", "pipefail", "-c"]
+
+# Generate Markdown release notes for VERSION without modifying the repository.
+release-notes version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    version="{{ version }}"
+    if git show-ref --verify --quiet "refs/tags/${version}"; then
+        revision="${version}"
+        previous="$(git describe --tags --abbrev=0 "${version}^")"
+    else
+        revision="HEAD"
+        previous="$(git describe --tags --abbrev=0 HEAD)"
+    fi
+
+    uv run git-cliff "${previous}..${revision}" \
+        --tag "${version}" \
+        --config keepachangelog \
+        --strip all
+
+# Add generated notes to an existing GitHub release (requires the GitHub CLI).
+publish-release-notes version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    command -v gh >/dev/null || {
+        echo "The GitHub CLI (gh) is required to publish release notes." >&2
+        exit 1
+    }
+
+    notes_file="$(mktemp)"
+    trap 'rm -f "${notes_file}"' EXIT
+    uv run just release-notes "{{ version }}" > "${notes_file}"
+    gh release edit "{{ version }}" --notes-file "${notes_file}"
+
+# Bump VERSION_KIND (patch, minor, or major), commit, tag, and push the release.
+release version_kind:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    version_kind="{{ version_kind }}"
+    case "${version_kind}" in
+        patch|minor|major) ;;
+        *)
+            echo "Version kind must be one of: patch, minor, major." >&2
+            exit 2
+            ;;
+    esac
+
+    if [[ "$(git branch --show-current)" != "main" ]]; then
+        echo "Releases must be created from the main branch." >&2
+        exit 1
+    fi
+    if [[ -n "$(git status --porcelain)" ]]; then
+        echo "The working tree must be clean before creating a release." >&2
+        exit 1
+    fi
+
+    git fetch origin main --tags
+    if [[ "$(git rev-parse HEAD)" != "$(git rev-parse origin/main)" ]]; then
+        echo "Local main must match origin/main before creating a release." >&2
+        exit 1
+    fi
+
+    uv run pytest
+    uv run bumpver update "--${version_kind}" --ignore-vcs-tag --no-fetch
+    version="$(uv run python -c 'from pytest_docker_compose import __version__; print(__version__)')"
+
+    uv run just release-notes "${version}"
+    git push origin main
+    git push origin "${version}"
+
+    echo
+    echo "Release ${version} pushed. Once GitHub creates the release, publish its notes with:"
+    echo "  uv run just publish-release-notes ${version}"

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pytest-docker-compose-v2
-Version: 0.2.0
+Version: 0.3.0
 Summary: Manages Docker containers during your integration tests
 Project-URL: repository, https://github.com/radusuciu/pytest-docker-compose-v2
 Author: Radu Suciu, Thomas Meckel, Roald Storm, Phoenix Zerin
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.10
 Requires-Dist: pytest<10,>=7.2.2
-Requires-Dist: python-on-whales<1,>=0.69.0
+Requires-Dist: python-on-whales<1,>=0.71.0
 Description-Content-Type: text/markdown
 
 [![PyPI pyversions](https://img.shields.io/pypi/pyversions/pytest-docker-compose-v2.svg)](https://pypi.python.org/pypi/pytest-docker-compose-v2/)
@@ -103,7 +103,53 @@ The fixtures called `[scope]_scoped_container_getter` will wait until every cont
 
 However, just because a container is up does not mean that the services running on it are ready to accept incoming requests yet!
 
-If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), make sure that your fixtures account for this.
+#### Option 1: Using Docker Compose Healthchecks (Recommended)
+
+The plugin can use Docker Compose's native `--wait` functionality with healthchecks defined in your `docker-compose.yml`. This lets Docker Compose handle waiting for services to be ready.
+
+First, define healthchecks in your `docker-compose.yml`:
+
+```yaml
+services:
+  my_api_service:
+    build: ./api
+    ports:
+      - "5000:5000"
+    depends_on:
+      my_db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+  my_db:
+    image: postgres:15
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+```
+
+Then opt in to waiting when you run pytest:
+
+```shell
+pytest --docker-compose-wait
+```
+
+You can also specify a timeout (in seconds):
+
+```shell
+pytest --docker-compose-wait --docker-compose-wait-timeout=120
+```
+
+Waiting remains opt-in for backward compatibility. It is planned to become the default in version 1.0.
+
+#### Option 2: Python-based Wait Fixtures
+
+If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), you can implement custom wait logic in your fixtures.
 
 Here's an example of a fixture called `wait_for_api` that waits for an HTTP service to come online before a test called `test_read_and_write` can run.
 
@@ -221,5 +267,47 @@ pytest --docker-compose-remove-volumes
 
 This option will be ignored if the plugin is not used. Again, this option can also be added to the `pytest.ini` file.
 
+### Command Line Options Summary
+
+| Option | Description |
+|--------|-------------|
+| `--docker-compose` | Path to docker-compose.yml file or directory containing one. Multiple files can be specified with commas. |
+| `--docker-compose-no-build` | Skip building Docker images before running tests. |
+| `--docker-compose-remove-volumes` | Remove container volumes after tests complete. |
+| `--use-running-containers` | Use already running containers instead of starting new ones. |
+| `--docker-compose-wait` | Wait for services to be healthy before running tests (requires healthcheck definitions). |
+| `--docker-compose-wait-timeout` | Timeout in seconds when waiting for services to be healthy. |
+
 For more examples on how to use this plugin look at the testing suite of this plugin itself! It will give you some examples for configuring `pyproject.toml` and how to use the different fixtures to run docker containers.
 
+## Releasing
+
+Release commands are managed with `just`, which is installed by the development
+dependency group:
+
+```shell
+uv sync
+```
+
+Preview the release notes for a version without modifying the repository:
+
+```shell
+uv run just release-notes 0.3.0
+```
+
+Create and push a release from a clean, up-to-date `main` branch by choosing a
+semantic version increment:
+
+```shell
+uv run just release patch
+uv run just release minor
+uv run just release major
+```
+
+The command runs the tests, updates the package version, creates the version
+commit and tag, and pushes both. Once GitHub Actions has created the GitHub
+Release, its generated notes can be added with:
+
+```shell
+uv run just publish-release-notes 0.3.0
+```

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/README.md

@@ -76,7 +76,53 @@ The fixtures called `[scope]_scoped_container_getter` will wait until every cont
 
 However, just because a container is up does not mean that the services running on it are ready to accept incoming requests yet!
 
-If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), make sure that your fixtures account for this.
+#### Option 1: Using Docker Compose Healthchecks (Recommended)
+
+The plugin can use Docker Compose's native `--wait` functionality with healthchecks defined in your `docker-compose.yml`. This lets Docker Compose handle waiting for services to be ready.
+
+First, define healthchecks in your `docker-compose.yml`:
+
+```yaml
+services:
+  my_api_service:
+    build: ./api
+    ports:
+      - "5000:5000"
+    depends_on:
+      my_db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+  my_db:
+    image: postgres:15
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+```
+
+Then opt in to waiting when you run pytest:
+
+```shell
+pytest --docker-compose-wait
+```
+
+You can also specify a timeout (in seconds):
+
+```shell
+pytest --docker-compose-wait --docker-compose-wait-timeout=120
+```
+
+Waiting remains opt-in for backward compatibility. It is planned to become the default in version 1.0.
+
+#### Option 2: Python-based Wait Fixtures
+
+If your tests need to wait for a particular condition (for example, to wait for an HTTP health check endpoint to send back a 200 response), you can implement custom wait logic in your fixtures.
 
 Here's an example of a fixture called `wait_for_api` that waits for an HTTP service to come online before a test called `test_read_and_write` can run.
 
@@ -194,5 +240,47 @@ pytest --docker-compose-remove-volumes
 
 This option will be ignored if the plugin is not used. Again, this option can also be added to the `pytest.ini` file.
 
+### Command Line Options Summary
+
+| Option | Description |
+|--------|-------------|
+| `--docker-compose` | Path to docker-compose.yml file or directory containing one. Multiple files can be specified with commas. |
+| `--docker-compose-no-build` | Skip building Docker images before running tests. |
+| `--docker-compose-remove-volumes` | Remove container volumes after tests complete. |
+| `--use-running-containers` | Use already running containers instead of starting new ones. |
+| `--docker-compose-wait` | Wait for services to be healthy before running tests (requires healthcheck definitions). |
+| `--docker-compose-wait-timeout` | Timeout in seconds when waiting for services to be healthy. |
+
 For more examples on how to use this plugin look at the testing suite of this plugin itself! It will give you some examples for configuring `pyproject.toml` and how to use the different fixtures to run docker containers.
 
+## Releasing
+
+Release commands are managed with `just`, which is installed by the development
+dependency group:
+
+```shell
+uv sync
+```
+
+Preview the release notes for a version without modifying the repository:
+
+```shell
+uv run just release-notes 0.3.0
+```
+
+Create and push a release from a clean, up-to-date `main` branch by choosing a
+semantic version increment:
+
+```shell
+uv run just release patch
+uv run just release minor
+uv run just release major
+```
+
+The command runs the tests, updates the package version, creates the version
+commit and tag, and pushes both. Once GitHub Actions has created the GitHub
+Release, its generated notes can be added with:
+
+```shell
+uv run just publish-release-notes 0.3.0
+```

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 ]
 dependencies = [
     "pytest>=7.2.2,<10",
-    "python-on-whales>=0.69.0,<1"
+    "python-on-whales>=0.71.0,<1"
 ]
 requires-python = ">=3.10"
 readme = "README.md"
@@ -58,6 +58,7 @@ dev = [
     "tox>=4.30.3",
     "tox-uv>=1.28.1",
     "pytest>=8,<10",
+    "rust-just>=1.58.0",
 ]
 
 [tool.hatch.version]
@@ -67,23 +68,24 @@ path = "pytest_docker_compose/__init__.py"
 packages = ["pytest_docker_compose"]
 
 [tool.pytest.ini_options]
-addopts = "-m 'not (should_fail or multiple_compose_files)' '--docker-compose' './tests/pytest_docker_compose_tests/my_network' '--docker-compose-no-build'"
+addopts = "-m 'not (should_fail or multiple_compose_files or wait_for_healthcheck)' '--docker-compose' './tests/pytest_docker_compose_tests/my_network' '--docker-compose-no-build'"
 markers = [
     "should_fail: marks a set of test that should throw an error when run",
     "multiple_compose_files: marks a test that uses more than one compose file",
+    "wait_for_healthcheck: marks tests that use --docker-compose-wait with healthchecks",
 ]
 minversion = "7.2"
 
 [tool.ruff]
 line-length = 88
-target-version = "py311"
+target-version = "py310"
 
 [tool.ruff.lint.mccabe]
 # Unlike Flake8, default to a complexity level of 10.
 max-complexity = 10
 
 [tool.bumpver]
-current_version = "0.2.0"
+current_version = "0.3.0"
 version_pattern = "MAJOR.MINOR.PATCH[GITHASH]"
 commit_message = "bump version {old_version} -> {new_version}"
 commit = true
@@ -122,4 +124,5 @@ commands=
     docker compose -f tests/pytest_docker_compose_tests/my_network/docker-compose.yml up -d
     pytest --use-running-containers
     docker compose -f tests/pytest_docker_compose_tests/my_network/docker-compose.yml down -v
+    pytest -m wait_for_healthcheck --docker-compose ./tests/pytest_docker_compose_tests/my_network --docker-compose-wait
 """

pytest_docker_compose_v2-0.3.0/pytest_docker_compose/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/pytest_docker_compose/plugin.py

@@ -11,8 +11,6 @@ from python_on_whales.components.container.cli_wrapper import Container
 class ContainersAlreadyExist(Exception):
     """Raised when running containers are unexpectedly found"""
 
-    pass
-
 
 __all__ = [
     "DockerComposePlugin",
@@ -125,6 +123,21 @@ class DockerComposePlugin:
             "instead of calling 'docker-compose up'",
         )
 
+        group.addoption(
+            "--docker-compose-wait",
+            action="store_true",
+            default=False,
+            help="Wait for services to be healthy before running tests "
+            "(requires healthcheck definitions in docker-compose.yml)",
+        )
+
+        group.addoption(
+            "--docker-compose-wait-timeout",
+            type=int,
+            default=None,
+            help="Timeout in seconds when waiting for services to be healthy",
+        )
+
     @pytest.fixture(scope="session")
     def docker_project(self, request):
         """
@@ -144,10 +157,8 @@ class DockerComposePlugin:
 
             if not docker_compose.is_file():
                 raise ValueError(
-                    "Unable to find `{docker_compose}` "
-                    "for integration tests.".format(
-                        docker_compose=docker_compose.absolute(),
-                    ),
+                    f"Unable to find `{docker_compose.absolute()}` "
+                    "for integration tests.",
                 )
 
             compose_files.append(docker_compose)
@@ -183,11 +194,14 @@ class DockerComposePlugin:
                     )
                 )
             current_containers = project.compose.ps()
-            project.compose.up(detach=True, quiet=True)
-            containers = [
-                key for key, value in project.compose.config().services.items()
-            ]
-            if not len(current_containers) == len(containers):
+            project.compose.up(
+                detach=True,
+                quiet=True,
+                wait=request.config.getoption("--docker-compose-wait"),
+                wait_timeout=request.config.getoption("--docker-compose-wait-timeout"),
+            )
+            containers = list(project.compose.config().services.keys())
+            if len(current_containers) != len(containers):
                 warnings.warn(
                     UserWarning(
                         "You used the '--use-running-containers' but "
@@ -197,11 +211,9 @@ class DockerComposePlugin:
                 )
         else:
             if any(
-                (
-                    container
-                    for container in project.compose.ps()
-                    if container.state.running
-                )
+                container
+                for container in project.compose.ps()
+                if container.state.running
             ):
                 raise ContainersAlreadyExist(
                     "There are already existing containers, please remove all "
@@ -228,18 +240,21 @@ class DockerComposePlugin:
             now = datetime.now(timezone.utc)
             if not request.config.getoption("--use-running-containers"):
                 if any(
-                    (
-                        container
-                        for container in docker_project.compose.ps()
-                        if container.state.running
-                    )
+                    container
+                    for container in docker_project.compose.ps()
+                    if container.state.running
                 ):
                     raise ContainersAlreadyExist(
                         "pytest-docker-compose tried to start containers but there are"
-                        " already running containers: %s, you probably scoped your"
-                        " tests wrong" % docker_project.compose.ps()
+                        f" already running containers: {docker_project.compose.ps()},"
+                        " you probably scoped your tests wrong"
                     )
-                docker_project.compose.up(detach=True, quiet=True)
+                docker_project.compose.up(
+                    detach=True,
+                    quiet=True,
+                    wait=request.config.getoption("--docker-compose-wait"),
+                    wait_timeout=request.config.getoption("--docker-compose-wait-timeout"),
+                )
                 if not any(docker_project.compose.ps()):
                     raise ValueError("`docker-compose` didn't launch any containers!")
 
@@ -249,7 +264,7 @@ class DockerComposePlugin:
             if request.config.getoption("--verbose"):
                 containers = docker_project.compose.ps()
                 for container in sorted(containers, key=lambda c: c.name):
-                    header = "Logs from {name}:".format(name=container.name)
+                    header = f"Logs from {container.name}:"
                     print(header, "\n", "=" * len(header))
                     print(
                         container.logs(since=now) or "(no logs)",
@@ -261,16 +276,13 @@ class DockerComposePlugin:
                     volumes=request.config.getoption("--docker-compose-remove-volumes")
                 )
 
-        scoped_containers_fixture.__wrapped__.__doc__ = (
-            """
+        scoped_containers_fixture.__wrapped__.__doc__ = f"""
             Spins up the containers for the Docker project and returns an
             object that can retrieve the containers. The returned containers
             all have one additional attribute called network_info to simplify
             accessing the hostnames and exposed port numbers for each container.
-            This set of containers is scoped to '%s'
+            This set of containers is scoped to '{scope}'
             """
-            % scope
-        )
         return scoped_containers_fixture
 
 
@@ -307,8 +319,8 @@ class ContainerGetter:
         if not containers_running.get(key):
             warnings.warn(
                 UserWarning(
-                    "The service '%s' only has a stopped container, "
-                    "it stopped with '%s'" % (key, container.state.status)
+                    f"The service '{key}' only has a stopped container, "
+                    f"it stopped with '{container.state.status}'"
                 )
             )
         network_info = create_network_info_for_container(container)

pytest_docker_compose_v2-0.3.0/tests/pytest_docker_compose_tests/my_network/a_buildable_container/requirements.txt

@@ -0,0 +1,3 @@
+uvicorn==0.53.0
+psycopg2-binary==2.9.13
+fastapi==0.141.1

pytest_docker_compose_v2-0.3.0/tests/pytest_docker_compose_tests/my_network/docker-compose.yml

@@ -0,0 +1,33 @@
+services:
+  my_api_service:
+    build: ./a_buildable_container
+    ports:
+      - "5000:5000"
+    depends_on:
+      my_db:
+        condition: service_healthy
+      my_short_lived_service:
+        condition: service_completed_successfully
+    restart: on-failure
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/')"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+  my_db:
+    image: postgres:11.2-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_HOST_AUTH_METHOD: trust
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+      start_period: 5s
+  my_short_lived_service:
+    build: ./a_buildable_container
+    entrypoint: /bin/echo
+    command: "Echoing"

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/tests/pytest_docker_compose_tests/test_function_scoping_fixtures.py

@@ -5,7 +5,6 @@ import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
-
 @pytest.fixture(scope="function")
 def wait_for_api(function_scoped_container_getter):
     """Wait for the api from my_api_service to become responsive"""

{pytest_docker_compose_v2-0.2.0 → pytest_docker_compose_v2-0.3.0}/tests/pytest_docker_compose_tests/test_module_scoping_fixtures.py

@@ -6,7 +6,6 @@ from requests.adapters import HTTPAdapter
 
 import pytest
 
-
 @pytest.fixture(scope="module")
 def wait_for_api(module_scoped_container_getter):
     """Wait for the api from my_api_service to become responsive"""

pytest_docker_compose_v2-0.3.0/tests/pytest_docker_compose_tests/test_wait_for_healthcheck.py

@@ -0,0 +1,48 @@
+"""
+Tests for the --docker-compose-wait feature.
+
+These tests verify that when --docker-compose-wait is used, containers
+are healthy (based on their healthcheck definitions) before tests run.
+"""
+
+import pytest
+import requests
+
+pytestmark = pytest.mark.wait_for_healthcheck
+
+
+@pytest.fixture(scope="function")
+def api_service(function_scoped_container_getter):
+    """Get the API service container."""
+    container = function_scoped_container_getter.get("my_api_service")
+    assert hasattr(container, "network_info")
+    assert container.network_info
+    return container
+
+
+def test_container_is_healthy_when_wait_flag_used(api_service):
+    """
+    When --docker-compose-wait is used, the container should already be healthy
+    by the time the test runs, meaning we can immediately make requests without
+    any retry logic.
+    """
+    network_info = api_service.network_info[0]
+    api_url = f"http://{network_info.hostname}:{network_info.host_port}/"
+
+    # With --docker-compose-wait, the service should be immediately available
+    # without needing retry logic
+    response = requests.get(api_url, timeout=5)
+    assert response.status_code == 200
+    assert response.json() == {"Hello": "World"}
+
+
+def test_db_container_is_healthy(function_scoped_container_getter):
+    """
+    Verify the database container is also healthy when --docker-compose-wait is used.
+    """
+    container = function_scoped_container_getter.get("my_db")
+    # Container should be running and healthy
+    assert container.state.running
+    # With --docker-compose-wait, the health status should be "healthy"
+    assert container.state.health is not None
+    assert container.state.health.status == "healthy"