Buckets:

download
raw
14.5 kB
"""Shared helpers for testcontainers-backed tests.
Several test packages (``tests/connectors/``, ``tests/services/ariel_search/``,
``tests/e2e/``) spin up real containers and must degrade to a skip rather than
an error when the host has no Docker engine. This module is the single home for
the environment probes and start helpers they share.
Two start helpers live here because container suites split into two kinds, and
which one a suite wants is a real decision rather than a preference:
:func:`start_or_skip` for suites where an absent engine must not fail a
contributor's run, and :func:`start_or_fail` for suites that have already
established a daemon is present and for which a skip would be a vacuous green.
They sit side by side so that contrast is visible at the point of choosing.
The leading underscore keeps the module out of pytest collection: ``python_files``
matches ``test_*.py``/``*_test.py`` only, and a helper module that got collected
would report its imports as test failures.
Note on imports: ``docker`` is a ``dev``-extra dependency, so it is imported
lazily inside the functions that need it. A module-scope import would turn a
missing extra into a collection error for every test package that imports from
here. ``requests`` is a base dependency and is safe at module scope.
"""
import logging
import shutil
import subprocess
import time
from collections.abc import Callable
from contextlib import suppress
from typing import TypeVar
import pytest
import requests
logger = logging.getLogger(__name__)
ContainerT = TypeVar("ContainerT")
def is_docker_available() -> bool:
"""Return True if the Docker daemon is reachable.
Used to gate testcontainers-backed fixtures so that contributors
without a running Docker engine see a skip rather than an error.
"""
try:
import docker
client = docker.from_env()
client.ping()
return True
except Exception as e:
logger.warning(f"Docker not available: {e}")
return False
#: How long ``docker info`` may take before the probe gives up. A healthy
#: daemon on a loaded host can take well over ten seconds to answer; the
#: figure is generous so that "slow" is reported as slow rather than as absent.
DOCKER_CLI_PROBE_TIMEOUT = 30.0
def docker_cli_unavailable_reason(*, timeout: float = DOCKER_CLI_PROBE_TIMEOUT) -> str | None:
"""Why the ``docker`` CLI cannot be used right now, or ``None`` when it can.
For suites that shell out to ``docker build`` / ``docker run`` rather than
going through the SDK, so the CLI itself has to be on ``PATH`` and the
daemon behind it has to answer. The outcomes are worded apart because they
call for different responses, and a skip reason is the only place a test
report shows them: a probe that timed out names a loaded host (the suite
would run — later), an unreachable daemon names an engine that is off, and
a missing CLI names a machine that never had one. Collapsing the three into
"docker not available" made a saturated developer box indistinguishable
from one with no engine (#820).
Args:
timeout: Seconds to wait for ``docker info``.
Returns:
``None`` when the CLI works; otherwise a one-line reason suitable for
``pytest.mark.skipif(..., reason=...)``.
"""
if shutil.which("docker") is None:
return "docker CLI not on PATH"
try:
probe = subprocess.run(["docker", "info"], capture_output=True, text=True, timeout=timeout)
except subprocess.TimeoutExpired:
return f"docker probe timed out after {timeout:g}s (daemon present but slow?)"
except OSError as exc:
return f"docker CLI could not be run: {exc}"
if probe.returncode != 0:
lines = (probe.stderr or probe.stdout).strip().splitlines()
detail = lines[-1].strip() if lines else f"exit {probe.returncode}"
return f"docker daemon not reachable: {detail}"
return None
def is_image_present(reference: str) -> bool:
"""Return True if a local image matching ``reference`` exists.
Distinguishes "this machine has no engine" from "this machine has an engine
but was never asked to build the image", which are different situations that
a plain start failure reports identically.
Args:
reference: Image reference, e.g. ``osprey-qmd:local-validate``.
Returns:
True when the local daemon can resolve the reference. False on an absent
image, an unreachable daemon, or a missing ``docker`` package -- callers
gate on :func:`is_docker_available` first, so those collapse together.
"""
try:
import docker
docker.from_env().images.get(reference)
return True
except Exception as e:
logger.warning(f"Image {reference} not present: {e}")
return False
def stop_quietly(container: object) -> None:
"""Stop a container, swallowing teardown errors.
``stop()`` calls ``remove(force=True)``, which raises ``NotFound`` when the
container is already gone — the same case testcontainers' own reaper
suppresses. Letting that escape turns a clean run into an ERROR at teardown.
Used both to discard a container built by a failed start attempt and as the
teardown for fixtures that own one.
"""
with suppress(Exception):
container.stop() # type: ignore[attr-defined]
def start_or_skip(
factory: Callable[[], ContainerT],
label: str,
*,
backoff: float = 3.0,
) -> ContainerT:
"""Start a container built by ``factory``, skipping the test on failure.
``factory`` must *build and return a new container object* on every call.
A retry always builds a fresh one: ``DockerContainer.start()`` assigns
``self._container`` before the readiness wait, so reusing the object after a
timeout would orphan the container started by the first attempt.
The ``except`` chain is ordered, and the order is load-bearing because
``ImageNotFound ⊂ NotFound ⊂ APIError ⊂ RequestException``:
* ``docker.errors.NotFound`` — a missing image or resource. Not transient,
so skip immediately; a second 120s readiness wait cannot help.
* ``requests.exceptions.RequestException`` or the BUILTIN ``ConnectionError``
— a flaky daemon or registry call, or testcontainers' own port-publish
race. Retried once after ``backoff`` seconds.
* ``Exception`` — anything else, notably ``TimeoutError``. Skip immediately.
The builtin ``ConnectionError`` is named explicitly because it is NOT one of
the requests errors, however much it looks like one:
``requests.exceptions.ConnectionError`` is a ``RequestException`` and is
caught by that arm, while the builtin sits on the other branch of
``OSError`` and is not. Testcontainers raises the builtin one directly when
a container's port mapping is not published yet
(``docker_client.py``, "Port mapping for container ... is not available"),
which is the ryuk reaper racing its own port publish — testcontainers itself
classes it transient (``waiting_utils.TRANSIENT_EXCEPTIONS``). Without this,
that race fell through to the final ``except Exception`` and skipped on the
spot, turning a whole container module into an all-skipped run that a reader
cannot tell apart from a host with no Docker. A silent green on the only
real-server coverage a route has is worse than a red one.
A host with no Docker engine at all is untouched by this and still skips on
the first attempt: ``docker.from_env()`` raises ``DockerException``, which is
neither a ``RequestException`` nor a ``ConnectionError`` and lands in the
final arm.
``backoff`` is keyword-only so tests can pass ``backoff=0`` instead of
paying real wall clock for the retry sleep.
Args:
factory: Zero-argument callable returning a fresh, unstarted container.
label: Human-readable name for the container, used in skip messages.
backoff: Seconds to wait before the single retry.
Returns:
The started container.
Raises:
Skipped: Via ``pytest.skip`` when the container cannot be started.
"""
import docker.errors
max_attempts = 2
for attempt in range(1, max_attempts + 1):
container = factory()
try:
container.start() # type: ignore[attr-defined]
return container
except docker.errors.NotFound as exc:
stop_quietly(container)
pytest.skip(_skip_message(label, exc, attempt))
except (requests.exceptions.RequestException, ConnectionError) as exc:
stop_quietly(container)
if attempt == max_attempts:
pytest.skip(_skip_message(label, exc, attempt))
logger.warning(
f"{label}: start attempt {attempt} failed "
f"({type(exc).__name__}: {exc}); retrying in {backoff}s"
)
time.sleep(backoff)
except Exception as exc:
stop_quietly(container)
pytest.skip(_skip_message(label, exc, attempt))
raise AssertionError("unreachable: retry loop always skips or returns")
#: Attempts a container start gets before a fail-hard lane gives up. The failure
#: this absorbs is a testcontainers race, not a slow image: it reads the
#: published port mapping the instant the container starts and raises when
#: Docker has not published it yet. Builtin ``ConnectionError`` is an
#: ``OSError``, so a helper that skips on any exception would turn that race
#: into a vacuous green.
CONTAINER_START_ATTEMPTS = 4
def start_or_fail(
factory: Callable[[], ContainerT],
label: str,
port: int,
*,
backoff: float = 2.0,
) -> tuple[ContainerT, int]:
"""Start a container built by ``factory`` and read its published port.
The fail-hard counterpart to :func:`start_or_skip`, for lanes that have
already established a daemon is present. Two things make ``start_or_skip``
wrong for such a lane, and dangerously so:
1. Docker availability is checked before this is called, so past this point
a container that will not start is a defect in the image, the corpus or
the host, not an absent optional dependency — and a lane whose whole job
is to prove a container-backed feature works must not be able to report
success having executed nothing.
2. The commonest failure is transient and ``start_or_skip`` does not retry
it. testcontainers raises a **builtin** ``ConnectionError`` ("Port mapping
for container ... is not available"). Builtin ``ConnectionError`` is an
``OSError``, not a ``requests.exceptions.RequestException``, so it lands
in that helper's bare ``except Exception`` and skips on the first attempt.
Observed on a second consecutive run: ``12 skipped ... exit 0``.
**Reading the published port is part of the retried operation, not a step
after it.** testcontainers queries the mapping the instant the container
starts, so the same race bites twice. Retrying only ``start()`` leaves the
second one live and it surfaces as a container that started fine and a test
that died reading its port — observed as ``23 errors`` in a run whose
containers were all healthy. Retrying inside the loop also means a failed
attempt is discarded and a *fresh* container is built, rather than the port
being re-read from the same one that never published it.
Args:
factory: Zero-argument callable returning a fresh, unstarted container.
Called again per attempt — ``start()`` assigns the container handle
before its readiness wait, so reusing the object would orphan the
container a failed attempt started.
label: Human-readable name for the container, used in the failure.
port: Container port whose host mapping to resolve.
backoff: Seconds between attempts.
Returns:
Tuple of the started container and its published host port.
Raises:
AssertionError: If every attempt failed.
"""
failures: list[str] = []
for attempt in range(1, CONTAINER_START_ATTEMPTS + 1):
container = factory()
try:
container.start() # type: ignore[attr-defined]
return container, int(container.get_exposed_port(port)) # type: ignore[attr-defined]
except Exception as exc: # noqa: BLE001 — every start failure is retried alike
stop_quietly(container)
failures.append(f"attempt {attempt}: {type(exc).__name__}: {exc}")
logger.warning("%s: start attempt %d failed (%s)", label, attempt, exc)
if attempt < CONTAINER_START_ATTEMPTS:
time.sleep(backoff)
remedy = ""
if any("testcontainers-ryuk" in failure for failure in failures):
# The first failure is the cause and the 409s are cascade: testcontainers
# left a half-started reaper behind and every retry collides with its
# name. Surfaced here because the cascade buries the real first line and
# reads like a defect in the image. See tests/README.md §6 "Containers".
remedy = (
"\n\nThe 409 'container name testcontainers-ryuk-... already in use' lines are "
"CASCADE, not the cause — read the first failure above. testcontainers' own "
"reaper races Docker Desktop's port forwarder on macOS. Remove the stale "
"reaper (`docker rm -f <its id>`) and re-run with "
"TESTCONTAINERS_RYUK_DISABLED=1, which tests/README.md recommends for local "
"macOS runs only — every fixture here stops its own containers. Do NOT set it "
"in CI; Linux daemons do not show the race."
)
raise AssertionError(
f"{label}: container would not start in {CONTAINER_START_ATTEMPTS} attempts, and the "
f"docker daemon is reachable — this is a real failure, not a missing dependency.\n"
+ "\n".join(failures)
+ remedy
)
def _skip_message(label: str, exc: BaseException, attempt: int) -> str:
"""Build a skip message naming the container, attempt count, and cause.
The exception type *is* the diagnosis, so it is reported verbatim rather
than mapped onto a bucket taxonomy.
"""
return (
f"{label}: container failed to start after {attempt} attempt(s) — "
f"{type(exc).__name__}: {exc}"
)

Xet Storage Details

Size:
14.5 kB
·
Xet hash:
e0c90e0bfa7d8fcbcfa1296efac2b7636202a9422d0a55882cba11dacc729d45

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.