pytest-testcontainers 0.1.0__py3-none-any.whl

pytest_testcontainers/errors.py

@@ -0,0 +1,61 @@
+"""Plugin exception hierarchy.
+
+User-facing daemon/reuse/start failures are converted to
+``pytest.UsageError`` at maker boundaries (see ``makers.py``).
+``CleanSessionFixtureError`` is the only one preserved as-is for the
+user's test report — it is a test-time failure, not a setup
+misconfiguration.
+"""
+
+from __future__ import annotations
+
+
+class PytestTestcontainersError(RuntimeError):
+    """Base exception. Plugin-internal; user code rarely sees this."""
+
+
+class DockerNotRunningError(PytestTestcontainersError):
+    """``docker.from_env().ping()`` failed."""
+
+
+class ContainerStartError(PytestTestcontainersError):
+    """A container failed ``.start()``. Wraps the testcontainers exc."""
+
+
+class ReuseConflictError(PytestTestcontainersError):
+    """An existing reused container exists but cannot be brought back to running.
+
+    Typical cause: another process now holds the host port the container
+    was previously bound to.
+    """
+
+
+class CleanSessionFixtureError(PytestTestcontainersError):
+    """A clean-session fixture failed to issue an admin command.
+
+    Raised by ``tc_psql_db`` / ``tc_mysql_db`` / ``tc_mongo_db`` /
+    ``tc_redis_clean`` from BOTH execution paths (Python client and
+    ``docker exec``) so user code sees a single exception type.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        command: str,
+        stderr: str,
+        exit_code: int | None,
+    ) -> None:
+        super().__init__(message)
+        self.command = command
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        parts = [base, f"command={self.command!r}"]
+        if self.exit_code is not None:
+            parts.append(f"exit_code={self.exit_code}")
+        if self.stderr:
+            parts.append(f"stderr={self.stderr!r}")
+        return " | ".join(parts)

pytest_testcontainers/fixtures.py

@@ -0,0 +1,295 @@
+"""Pytest fixtures registered by the plugin.
+
+Three families per service:
+
+1. **Default session** (``tc_<svc>``) — one container per worker session.
+2. **Function-scoped** (``tc_<svc>_func``) — one container per test.
+3. **Clean-session** (``tc_<svc>_db`` / ``tc_redis_clean``) — session
+   container, per-test fresh DB/keyspace.
+
+Each fixture is replaced with a stub that raises :class:`pytest.UsageError`
+when ``--no-testcontainers`` (or ``PYTEST_TESTCONTAINERS=0``) is active.
+The maker layer is unaffected — it stays usable from non-pytest code.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pytest_testcontainers._internal.clean_session_admin import (
+    create_mysql_db,
+    create_postgres_db,
+    drop_mongo_db,
+    drop_mysql_db,
+    drop_postgres_db,
+    flush_redis,
+)
+from pytest_testcontainers._internal.conn_info import DbConnInfo
+from pytest_testcontainers._internal.port_resolver import normalize_host
+from pytest_testcontainers.errors import (
+    CleanSessionFixtureError,
+    DockerNotRunningError,
+    PytestTestcontainersError,
+)
+from pytest_testcontainers.makers import (
+    make_mongo,
+    make_mysql,
+    make_postgres,
+    make_rabbitmq,
+    make_redis,
+)
+from pytest_testcontainers.reuse import is_plugin_disabled
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from testcontainers.mongodb import MongoDbContainer
+    from testcontainers.mysql import MySqlContainer
+    from testcontainers.postgres import PostgresContainer
+    from testcontainers.rabbitmq import RabbitMqContainer
+    from testcontainers.redis import RedisContainer
+
+__all__ = [
+    "tc_mongo",
+    "tc_mongo_db",
+    "tc_mongo_func",
+    "tc_mysql",
+    "tc_mysql_db",
+    "tc_mysql_func",
+    "tc_psql",
+    "tc_psql_db",
+    "tc_psql_func",
+    "tc_rabbitmq",
+    "tc_rabbitmq_func",
+    "tc_redis",
+    "tc_redis_clean",
+    "tc_redis_func",
+]
+
+_DISABLED_MSG = (
+    "[pytest-testcontainers] disabled via --no-testcontainers / "
+    "PYTEST_TESTCONTAINERS=0; user expected to provide service externally"
+)
+
+
+def _check_enabled() -> None:
+    if is_plugin_disabled():
+        raise pytest.UsageError(_DISABLED_MSG)
+
+
+def _to_usage_error(exc: PytestTestcontainersError) -> pytest.UsageError:
+    """Convert plugin-internal exceptions to user-friendly pytest.UsageError."""
+    if isinstance(exc, DockerNotRunningError):
+        msg = (
+            "[pytest-testcontainers] Docker daemon is not reachable.\n"
+            "Is Docker Desktop / colima / Rancher Desktop running?\n"
+            "\n"
+            "Options:\n"
+            "  - start it and re-run pytest, OR\n"
+            "  - disable the plugin: --no-testcontainers (or "
+            "PYTEST_TESTCONTAINERS=0), OR\n"
+            "  - point at remote Docker via DOCKER_HOST.\n"
+            "\n"
+            f"Underlying error: {exc}"
+        )
+        return pytest.UsageError(msg)
+    return pytest.UsageError(f"[pytest-testcontainers] {exc}")
+
+
+# --------------------------------------------------------------------------
+# Postgres
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def tc_psql() -> Iterator[PostgresContainer]:
+    """Session-scoped Postgres container (default ``postgres:16``)."""
+    _check_enabled()
+    try:
+        with make_postgres() as pg:
+            yield pg
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_psql_func() -> Iterator[PostgresContainer]:
+    """Function-scoped fresh Postgres container — almost always wrong, see README."""
+    _check_enabled()
+    try:
+        with make_postgres() as pg:
+            yield pg
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_psql_db(tc_psql: PostgresContainer) -> Iterator[DbConnInfo]:
+    """Per-test fresh Postgres database on the session container."""
+    name = f"test_{secrets.token_hex(6)}"
+    create_postgres_db(tc_psql, name)
+    try:
+        yield DbConnInfo(
+            host=normalize_host(tc_psql.get_container_host_ip()),
+            port=int(tc_psql.get_exposed_port(5432)),
+            username=tc_psql.username,
+            password=tc_psql.password,
+            database=name,
+        )
+    finally:
+        try:
+            drop_postgres_db(tc_psql, name)
+        except CleanSessionFixtureError:
+            import logging
+
+            logging.getLogger("pytest_testcontainers").exception(
+                "tc_psql_db: DROP DATABASE %r failed during teardown", name
+            )
+            raise
+
+
+# --------------------------------------------------------------------------
+# Redis
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def tc_redis() -> Iterator[RedisContainer]:
+    _check_enabled()
+    try:
+        with make_redis() as r:
+            yield r
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_redis_func() -> Iterator[RedisContainer]:
+    _check_enabled()
+    try:
+        with make_redis() as r:
+            yield r
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_redis_clean(tc_redis: RedisContainer) -> Iterator[RedisContainer]:
+    """Session Redis container with ``FLUSHALL`` between tests."""
+    yield tc_redis
+    flush_redis(tc_redis)
+
+
+# --------------------------------------------------------------------------
+# MySQL
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def tc_mysql() -> Iterator[MySqlContainer]:
+    _check_enabled()
+    try:
+        with make_mysql() as my:
+            yield my
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_mysql_func() -> Iterator[MySqlContainer]:
+    _check_enabled()
+    try:
+        with make_mysql() as my:
+            yield my
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_mysql_db(tc_mysql: MySqlContainer) -> Iterator[DbConnInfo]:
+    name = f"test_{secrets.token_hex(6)}"
+    create_mysql_db(tc_mysql, name)
+    try:
+        yield DbConnInfo(
+            host=normalize_host(tc_mysql.get_container_host_ip()),
+            port=int(tc_mysql.get_exposed_port(3306)),
+            username=tc_mysql.username,
+            password=tc_mysql.password,
+            database=name,
+        )
+    finally:
+        try:
+            drop_mysql_db(tc_mysql, name)
+        except CleanSessionFixtureError:
+            import logging
+
+            logging.getLogger("pytest_testcontainers").exception(
+                "tc_mysql_db: DROP DATABASE %r failed during teardown", name
+            )
+            raise
+
+
+# --------------------------------------------------------------------------
+# MongoDB
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def tc_mongo() -> Iterator[MongoDbContainer]:
+    _check_enabled()
+    try:
+        with make_mongo() as m:
+            yield m
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_mongo_func() -> Iterator[MongoDbContainer]:
+    _check_enabled()
+    try:
+        with make_mongo() as m:
+            yield m
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_mongo_db(tc_mongo: MongoDbContainer) -> Iterator[DbConnInfo]:
+    name = f"test_{secrets.token_hex(6)}"
+    try:
+        yield DbConnInfo(
+            host=normalize_host(tc_mongo.get_container_host_ip()),
+            port=int(tc_mongo.get_exposed_port(27017)),
+            username=tc_mongo.username,
+            password=tc_mongo.password,
+            database=name,
+        )
+    finally:
+        try:
+            drop_mongo_db(tc_mongo, name)
+        except CleanSessionFixtureError:
+            import logging
+
+            logging.getLogger("pytest_testcontainers").exception(
+                "tc_mongo_db: dropDatabase %r failed during teardown", name
+            )
+            raise
+
+
+# --------------------------------------------------------------------------
+# RabbitMQ — no clean-session fixture (cleanup not obvious; user wires their own)
+# --------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def tc_rabbitmq() -> Iterator[RabbitMqContainer]:
+    _check_enabled()
+    try:
+        with make_rabbitmq() as rmq:
+            yield rmq
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc
+
+
+@pytest.fixture
+def tc_rabbitmq_func() -> Iterator[RabbitMqContainer]:
+    _check_enabled()
+    try:
+        with make_rabbitmq() as rmq:
+            yield rmq
+    except PytestTestcontainersError as exc:
+        raise _to_usage_error(exc) from exc

pytest_testcontainers/makers.py

@@ -0,0 +1,312 @@
+"""Public maker functions: ``make_postgres``, ``make_redis``, … .
+
+Each maker is a context manager wrapping the corresponding
+``testcontainers-python`` class. The maker layer holds:
+
+* daemon ping (cached on success);
+* reuse-name resolution + Ryuk disable + lookup-by-name choreography;
+* atexit safety net for one-shot (function-scoped) mode.
+
+The fixture layer (``fixtures.py``) is deliberately thin — it just calls
+these makers from inside ``@pytest.fixture`` functions.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from pytest_testcontainers._internal.docker_health import check_docker_daemon
+from pytest_testcontainers.containers import (
+    bind_to_running,
+    deregister_atexit_stop,
+    disable_ryuk_once,
+    find_existing_container,
+    register_atexit_stop,
+    restart_stopped_or_raise,
+    start_or_raise,
+)
+from pytest_testcontainers.reuse import (
+    is_reuse_enabled,
+    reuse_name_for,
+    sanitize_component,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from testcontainers.core.container import DockerContainer
+
+
+# --------------------------------------------------------------------------
+# Generic core
+# --------------------------------------------------------------------------
+def _service_slug_for(container_cls: type) -> str:
+    """Derive a service slug from ``Cls.__name__`` (§16 #5)."""
+    name = container_cls.__name__.lower()
+    if name.endswith("container"):
+        name = name[: -len("container")]
+    return sanitize_component(name) or "container"
+
+
+def _apply_env(container: DockerContainer, env: dict[str, str] | None) -> None:
+    if not env:
+        return
+    for key, value in env.items():
+        container.with_env(key, value)
+
+
+@contextmanager
+def _make_generic(
+    container_cls: type[DockerContainer],
+    *constructor_args: Any,
+    service_slug: str,
+    reuse_name: str | None,
+    env: dict[str, str] | None,
+    constructor_kwargs: dict[str, Any] | None = None,
+) -> Iterator[DockerContainer]:
+    """Shared lifecycle for every maker.
+
+    ``service_slug`` is the short slug used in reuse-name composition
+    (``psql``, ``redis``, …, or derived from ``Cls.__name__`` for the
+    generic ``make_container``).
+    """
+    constructor_kwargs = dict(constructor_kwargs or {})
+
+    check_docker_daemon()
+
+    reuse_on = is_reuse_enabled() or reuse_name is not None
+    name = reuse_name_for(service_slug, override=reuse_name) if reuse_on else None
+
+    if reuse_on:
+        disable_ryuk_once()
+
+    instance: DockerContainer | None = None
+    is_bound_to_existing = False
+
+    if reuse_on and name is not None:
+        existing = find_existing_container(name)
+        if existing is not None:
+            status = getattr(existing, "status", "")
+            if status == "running":
+                instance = bind_to_running(
+                    container_cls, existing, *constructor_args, **constructor_kwargs
+                )
+                _apply_env(instance, env)
+                is_bound_to_existing = True
+            elif status in {"exited", "created", "paused"}:
+                restart_stopped_or_raise(existing, name)
+                instance = bind_to_running(
+                    container_cls, existing, *constructor_args, **constructor_kwargs
+                )
+                _apply_env(instance, env)
+                is_bound_to_existing = True
+            # Any other status (e.g. "removing", "dead") — treat as
+            # "not usable", fall through to fresh start.
+
+    if instance is None:
+        instance = container_cls(*constructor_args, **constructor_kwargs)
+        if name is not None:
+            instance.with_name(name)
+        _apply_env(instance, env)
+
+        image_for_msg = constructor_kwargs.get("image") or (
+            constructor_args[0] if constructor_args else container_cls.__name__
+        )
+        start_or_raise(instance, str(image_for_msg))
+
+        if not reuse_on:
+            register_atexit_stop(instance)
+
+    try:
+        yield instance
+    finally:
+        # Reuse mode: leave the container alive for the next run.
+        # Bound-to-existing: we never owned it, never stop it.
+        # Any exception raised in the with-body propagates either way —
+        # we only do cleanup work, never `return` from finally.
+        if not (reuse_on or is_bound_to_existing):
+            # Deregister the atexit callback before stopping so the
+            # safety net doesn't double-fire on a now-removed container.
+            deregister_atexit_stop(instance)
+            try:
+                instance.stop()
+            except Exception:
+                # Logged + swallowed: cleanup-time failures must not
+                # mask the original test failure. Per §4.1.2.
+                import logging
+
+                logging.getLogger("pytest_testcontainers").exception(
+                    "cleanup: container.stop() failed for %s", service_slug
+                )
+
+
+# --------------------------------------------------------------------------
+# Service-specific makers
+# --------------------------------------------------------------------------
+def make_postgres(
+    image: str = "postgres:16",
+    *,
+    username: str = "test",
+    password: str = "test",
+    database: str = "test",
+    port: int = 5432,
+    env: dict[str, str] | None = None,
+    reuse_name: str | None = None,
+    **kwargs: Any,
+):
+    """Context manager wrapping ``PostgresContainer``."""
+    from testcontainers.postgres import PostgresContainer
+
+    constructor_kwargs: dict[str, Any] = {
+        "image": image,
+        "username": username,
+        "password": password,
+        "dbname": database,
+        "port": port,
+        **kwargs,
+    }
+    return _make_generic(
+        PostgresContainer,
+        service_slug="psql",
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=constructor_kwargs,
+    )
+
+
+def make_redis(
+    image: str = "redis:7-alpine",
+    *,
+    port: int = 6379,
+    env: dict[str, str] | None = None,
+    reuse_name: str | None = None,
+    **kwargs: Any,
+):
+    """Context manager wrapping ``RedisContainer``."""
+    from testcontainers.redis import RedisContainer
+
+    constructor_kwargs: dict[str, Any] = {
+        "image": image,
+        "port": port,
+        **kwargs,
+    }
+    return _make_generic(
+        RedisContainer,
+        service_slug="redis",
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=constructor_kwargs,
+    )
+
+
+def make_mysql(
+    image: str = "mysql:8",
+    *,
+    username: str = "test",
+    password: str = "test",
+    database: str = "test",
+    root_password: str = "test",
+    port: int = 3306,
+    env: dict[str, str] | None = None,
+    reuse_name: str | None = None,
+    **kwargs: Any,
+):
+    """Context manager wrapping ``MySqlContainer``."""
+    from testcontainers.mysql import MySqlContainer
+
+    constructor_kwargs: dict[str, Any] = {
+        "image": image,
+        "username": username,
+        "password": password,
+        "dbname": database,
+        "root_password": root_password,
+        "port": port,
+        **kwargs,
+    }
+    return _make_generic(
+        MySqlContainer,
+        service_slug="mysql",
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=constructor_kwargs,
+    )
+
+
+def make_mongo(
+    image: str = "mongo:7",
+    *,
+    username: str = "test",
+    password: str = "test",
+    port: int = 27017,
+    env: dict[str, str] | None = None,
+    reuse_name: str | None = None,
+    **kwargs: Any,
+):
+    """Context manager wrapping ``MongoDbContainer``."""
+    from testcontainers.mongodb import MongoDbContainer
+
+    constructor_kwargs: dict[str, Any] = {
+        "image": image,
+        "username": username,
+        "password": password,
+        "port": port,
+        **kwargs,
+    }
+    return _make_generic(
+        MongoDbContainer,
+        service_slug="mongo",
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=constructor_kwargs,
+    )
+
+
+def make_rabbitmq(
+    image: str = "rabbitmq:3-management",
+    *,
+    username: str = "guest",
+    password: str = "guest",
+    port: int = 5672,
+    env: dict[str, str] | None = None,
+    reuse_name: str | None = None,
+    **kwargs: Any,
+):
+    """Context manager wrapping ``RabbitMqContainer``."""
+    from testcontainers.rabbitmq import RabbitMqContainer
+
+    constructor_kwargs: dict[str, Any] = {
+        "image": image,
+        "username": username,
+        "password": password,
+        "port": port,
+        **kwargs,
+    }
+    return _make_generic(
+        RabbitMqContainer,
+        service_slug="rabbitmq",
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=constructor_kwargs,
+    )
+
+
+def make_container(
+    container_cls: type[DockerContainer],
+    *args: Any,
+    reuse_name: str | None = None,
+    env: dict[str, str] | None = None,
+    **kwargs: Any,
+):
+    """Generic escape hatch for services we don't ship a maker for.
+
+    Same plumbing (daemon ping, reuse, atexit, Ryuk-disable-when-reuse).
+    """
+    return _make_generic(
+        container_cls,
+        *args,
+        service_slug=_service_slug_for(container_cls),
+        reuse_name=reuse_name,
+        env=env,
+        constructor_kwargs=kwargs,
+    )