pytest-testcontainers 0.2.0__tar.gz → 0.2.2__tar.gz

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-06-29
+
+### Fixed
+
+- Restored the `reuse_name_for` name in `pytest_testcontainers.reuse` as a
+  backward-compatible alias of `container_name_for`. The template-based
+  container-naming feature renamed the function, and 0.2.1 shipped that rename —
+  which broke `pytest-testcontainers-django` < 0.2.5 (it imports the old name)
+  at import time. The alias keeps existing installs working; the default
+  `reuse_mode=True` matches the old function's byte-stable behavior.
+
+## [0.2.1] - 2026-06-29
+
+### Fixed
+
+- **`Docker daemon is not reachable` even though `docker ps` worked**, on setups
+  where the daemon lives on a non-default socket (OrbStack, colima, a stopped
+  Docker Desktop). `docker.from_env()` — used by docker-py, by
+  testcontainers' own client, and by Ryuk's socket bind-mount — honors
+  `DOCKER_HOST` but, unlike the `docker` CLI, ignores the active
+  `docker context`, so it fell back to `/var/run/docker.sock` (absent or a
+  dangling symlink) and crashed with `FileNotFoundError`. The plugin now
+  exports `DOCKER_HOST` from the active context before any client is built, so
+  the whole process resolves Docker the way the CLI does. An explicit
+  `DOCKER_HOST` still wins; with no resolvable context it falls back to the
+  platform default socket.
+
 ## [0.2.0] - 2026-06-18
 
 ### Added

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-testcontainers
-Version: 0.2.0
+Version: 0.2.2
 Summary: Named pytest fixtures and a maker convention on top of testcontainers-python.
 Project-URL: Homepage, https://github.com/iplweb/pytest-testcontainers
 Project-URL: Repository, https://github.com/iplweb/pytest-testcontainers
@@ -455,6 +455,53 @@ Every plumbing concern — daemon ping, reuse name, atexit cleanup,
 Ryuk-disable-when-reuse — applies. `args`/`kwargs` go to the upstream
 constructor verbatim.
 
+## Container names
+
+Every container the plugin starts is named so you can find it in `docker ps`
+(previously default-mode containers got random Docker names like
+`heuristic_cannon`). The name is built from a template:
+
+```
+{project}-tc-{service}-{branch}-{dirtag}-{worker}
+```
+
+e.g. `myproj-tc-psql-feature-x-3f9ac1b2-master`.
+
+Placeholders:
+
+| Placeholder | Meaning |
+|-------------|---------|
+| `{project}` | Project name (see precedence below). |
+| `{service}` | Service slug (`psql`, `redis`, `mysql`, `mongo`, `rabbitmq`, or derived from the container class). |
+| `{branch}`  | Current git branch (read from `.git/HEAD`, no subprocess). Detached HEAD → 12-char commit SHA. No repo → empty. |
+| `{dir}`     | Worktree-root basename. Readable, not collision-proof. |
+| `{dirtag}`  | 8-hex hash of the worktree-root absolute path. Disambiguates the same branch checked out in two directories. |
+| `{worker}`  | xdist worker id (`master` when not under xdist). |
+| `{rand}`    | 4 random hex chars. Empty in reuse mode; auto-appended in default mode when the template omits it. |
+
+Empty placeholders collapse cleanly (no `--`, no dangling dashes). Names are
+sanitized to Docker's charset and capped at 255 chars (trim + checksum).
+
+Override the template (CLI > env > pyproject > built-in default):
+
+```bash
+pytest --testcontainers-name-template='{project}-{service}-{branch}'
+# or
+export PYTEST_TESTCONTAINERS_NAME_TEMPLATE='{project}-{service}-{branch}'
+```
+
+```toml
+# pyproject.toml
+[tool.pytest_testcontainers]
+name_template = "{project}-{service}-{branch}"
+```
+
+The `{project}` component resolves as: `--testcontainers-project` →
+`PYTEST_TESTCONTAINERS_PROJECT` → `PROJECT_NAME` → `COMPOSE_PROJECT_NAME` →
+`pyproject.toml [project].name` → cwd basename.
+
+An unknown placeholder raises `NameTemplateError` listing the valid ones.
+
 ## Reuse mode
 
 For iterative dev loops where you don't want to pay container-start
@@ -467,9 +514,11 @@ pytest --testcontainers-reuse tests/
 ```
 
 What changes:
-- Each container gets a stable name `<project>-tc-<service>-<worker>`
-  (e.g. `myproject-tc-psql-master`). The project name comes from
-  `pyproject.toml [project].name`.
+- Each container gets a stable, identifiable name from the template
+  (default `{project}-tc-{service}-{branch}-{dirtag}-{worker}`), so reuse is
+  scoped per project **and** per git branch **and** per directory. Switching
+  branch or worktree yields a *new* container; the previous one lingers
+  (stopped) until you run `pytest --testcontainers-clean`.
 - Ryuk (testcontainers' reaper) is disabled so the named containers
   survive between runs.
 - On the next run we look up by name — found-and-running gets bound
@@ -491,6 +540,10 @@ own `PYTEST_TESTCONTAINERS_PROJECT` to avoid name collisions. The
 plugin doesn't auto-namespace by PID — that would defeat the "reuse
 across runs" point.
 
+> **Upgrading from 0.1.0:** reuse-mode names now encode branch + directory, so
+> containers reused from an older version are not found by name — a fresh one
+> is created and the old one lingers until `pytest --testcontainers-clean`.
+
 ## Configuration
 
 No TOML config table. The handful of toggles read at maker-call time:
@@ -502,6 +555,9 @@ No TOML config table. The handful of toggles read at maker-call time:
 | `PYTEST_TESTCONTAINERS=0`                 | Disable plugin fixtures (raise UsageError). |
 | `PYTEST_TESTCONTAINERS_REUSE=1`           | Reuse named containers across runs.         |
 | `PYTEST_TESTCONTAINERS_PROJECT=<name>`    | Override the `<project>` part of reuse names. |
+| `PROJECT_NAME=<name>`                     | Generic project-name source (below the plugin var). |
+| `COMPOSE_PROJECT_NAME=<name>`             | docker-compose's project var (below `PROJECT_NAME`). |
+| `PYTEST_TESTCONTAINERS_NAME_TEMPLATE=<t>` | Override the container-name template.       |
 | `PYTEST_TESTCONTAINERS_NO_DAEMON_CHECK=1` | Skip Docker daemon ping (rare).             |
 | `PYTEST_TESTCONTAINERS_QUIET=1`           | Suppress one-shot informational advisories. |
 
@@ -513,6 +569,7 @@ No TOML config table. The handful of toggles read at maker-call time:
 | `--testcontainers-reuse`        | `PYTEST_TESTCONTAINERS_REUSE=1`      |
 | `--testcontainers-no-reuse`     | force fresh-each-run mode                 |
 | `--testcontainers-project=NAME` | `PYTEST_TESTCONTAINERS_PROJECT=NAME` |
+| `--testcontainers-name-template=T` | `PYTEST_TESTCONTAINERS_NAME_TEMPLATE=T` |
 | `--testcontainers-clean`        | prune `<project>-tc-*` and exit 0    |
 
 CLI > env > defaults.
@@ -534,6 +591,25 @@ Options:
 Underlying error: ...
 ```
 
+### `docker ps` works but pytest says the daemon is unreachable
+
+You're almost certainly on a non-default **Docker context** — OrbStack,
+colima, or a Docker Desktop install where `/var/run/docker.sock` is missing
+or a dangling symlink. `docker.from_env()` (used by docker-py *and* by
+testcontainers internally) honors `DOCKER_HOST` but, unlike the `docker`
+CLI, ignores the active `docker context`. The plugin now resolves the active
+context's endpoint for you and exports `DOCKER_HOST` before any container is
+started, so it talks to the same daemon the CLI does.
+
+If it still fails, point it at the daemon explicitly — an explicit
+`DOCKER_HOST` always wins:
+
+```bash
+docker context inspect -f '{{.Endpoints.docker.Host}}'   # see the endpoint
+export DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock # e.g. OrbStack
+export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock # e.g. colima
+```
+
 When a stopped reused container can't be brought back (typically
 because the previously-mapped port is now held by something else):
 

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/README.md

@@ -383,6 +383,53 @@ Every plumbing concern — daemon ping, reuse name, atexit cleanup,
 Ryuk-disable-when-reuse — applies. `args`/`kwargs` go to the upstream
 constructor verbatim.
 
+## Container names
+
+Every container the plugin starts is named so you can find it in `docker ps`
+(previously default-mode containers got random Docker names like
+`heuristic_cannon`). The name is built from a template:
+
+```
+{project}-tc-{service}-{branch}-{dirtag}-{worker}
+```
+
+e.g. `myproj-tc-psql-feature-x-3f9ac1b2-master`.
+
+Placeholders:
+
+| Placeholder | Meaning |
+|-------------|---------|
+| `{project}` | Project name (see precedence below). |
+| `{service}` | Service slug (`psql`, `redis`, `mysql`, `mongo`, `rabbitmq`, or derived from the container class). |
+| `{branch}`  | Current git branch (read from `.git/HEAD`, no subprocess). Detached HEAD → 12-char commit SHA. No repo → empty. |
+| `{dir}`     | Worktree-root basename. Readable, not collision-proof. |
+| `{dirtag}`  | 8-hex hash of the worktree-root absolute path. Disambiguates the same branch checked out in two directories. |
+| `{worker}`  | xdist worker id (`master` when not under xdist). |
+| `{rand}`    | 4 random hex chars. Empty in reuse mode; auto-appended in default mode when the template omits it. |
+
+Empty placeholders collapse cleanly (no `--`, no dangling dashes). Names are
+sanitized to Docker's charset and capped at 255 chars (trim + checksum).
+
+Override the template (CLI > env > pyproject > built-in default):
+
+```bash
+pytest --testcontainers-name-template='{project}-{service}-{branch}'
+# or
+export PYTEST_TESTCONTAINERS_NAME_TEMPLATE='{project}-{service}-{branch}'
+```
+
+```toml
+# pyproject.toml
+[tool.pytest_testcontainers]
+name_template = "{project}-{service}-{branch}"
+```
+
+The `{project}` component resolves as: `--testcontainers-project` →
+`PYTEST_TESTCONTAINERS_PROJECT` → `PROJECT_NAME` → `COMPOSE_PROJECT_NAME` →
+`pyproject.toml [project].name` → cwd basename.
+
+An unknown placeholder raises `NameTemplateError` listing the valid ones.
+
 ## Reuse mode
 
 For iterative dev loops where you don't want to pay container-start
@@ -395,9 +442,11 @@ pytest --testcontainers-reuse tests/
 ```
 
 What changes:
-- Each container gets a stable name `<project>-tc-<service>-<worker>`
-  (e.g. `myproject-tc-psql-master`). The project name comes from
-  `pyproject.toml [project].name`.
+- Each container gets a stable, identifiable name from the template
+  (default `{project}-tc-{service}-{branch}-{dirtag}-{worker}`), so reuse is
+  scoped per project **and** per git branch **and** per directory. Switching
+  branch or worktree yields a *new* container; the previous one lingers
+  (stopped) until you run `pytest --testcontainers-clean`.
 - Ryuk (testcontainers' reaper) is disabled so the named containers
   survive between runs.
 - On the next run we look up by name — found-and-running gets bound
@@ -419,6 +468,10 @@ own `PYTEST_TESTCONTAINERS_PROJECT` to avoid name collisions. The
 plugin doesn't auto-namespace by PID — that would defeat the "reuse
 across runs" point.
 
+> **Upgrading from 0.1.0:** reuse-mode names now encode branch + directory, so
+> containers reused from an older version are not found by name — a fresh one
+> is created and the old one lingers until `pytest --testcontainers-clean`.
+
 ## Configuration
 
 No TOML config table. The handful of toggles read at maker-call time:
@@ -430,6 +483,9 @@ No TOML config table. The handful of toggles read at maker-call time:
 | `PYTEST_TESTCONTAINERS=0`                 | Disable plugin fixtures (raise UsageError). |
 | `PYTEST_TESTCONTAINERS_REUSE=1`           | Reuse named containers across runs.         |
 | `PYTEST_TESTCONTAINERS_PROJECT=<name>`    | Override the `<project>` part of reuse names. |
+| `PROJECT_NAME=<name>`                     | Generic project-name source (below the plugin var). |
+| `COMPOSE_PROJECT_NAME=<name>`             | docker-compose's project var (below `PROJECT_NAME`). |
+| `PYTEST_TESTCONTAINERS_NAME_TEMPLATE=<t>` | Override the container-name template.       |
 | `PYTEST_TESTCONTAINERS_NO_DAEMON_CHECK=1` | Skip Docker daemon ping (rare).             |
 | `PYTEST_TESTCONTAINERS_QUIET=1`           | Suppress one-shot informational advisories. |
 
@@ -441,6 +497,7 @@ No TOML config table. The handful of toggles read at maker-call time:
 | `--testcontainers-reuse`        | `PYTEST_TESTCONTAINERS_REUSE=1`      |
 | `--testcontainers-no-reuse`     | force fresh-each-run mode                 |
 | `--testcontainers-project=NAME` | `PYTEST_TESTCONTAINERS_PROJECT=NAME` |
+| `--testcontainers-name-template=T` | `PYTEST_TESTCONTAINERS_NAME_TEMPLATE=T` |
 | `--testcontainers-clean`        | prune `<project>-tc-*` and exit 0    |
 
 CLI > env > defaults.
@@ -462,6 +519,25 @@ Options:
 Underlying error: ...
 ```
 
+### `docker ps` works but pytest says the daemon is unreachable
+
+You're almost certainly on a non-default **Docker context** — OrbStack,
+colima, or a Docker Desktop install where `/var/run/docker.sock` is missing
+or a dangling symlink. `docker.from_env()` (used by docker-py *and* by
+testcontainers internally) honors `DOCKER_HOST` but, unlike the `docker`
+CLI, ignores the active `docker context`. The plugin now resolves the active
+context's endpoint for you and exports `DOCKER_HOST` before any container is
+started, so it talks to the same daemon the CLI does.
+
+If it still fails, point it at the daemon explicitly — an explicit
+`DOCKER_HOST` always wins:
+
+```bash
+docker context inspect -f '{{.Endpoints.docker.Host}}'   # see the endpoint
+export DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock # e.g. OrbStack
+export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock # e.g. colima
+```
+
 When a stopped reused container can't be brought back (typically
 because the previously-mapped port is now held by something else):
 

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-testcontainers"
-version = "0.2.0"
+version = "0.2.2"
 description = "Named pytest fixtures and a maker convention on top of testcontainers-python."
 readme = "README.md"
 requires-python = ">=3.10"

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/src/pytest_testcontainers/__init__.py

@@ -7,6 +7,7 @@ from pytest_testcontainers.errors import (
     CleanSessionFixtureError,
     ContainerStartError,
     DockerNotRunningError,
+    NameTemplateError,
     PytestTestcontainersError,
     ReuseConflictError,
 )
@@ -24,6 +25,7 @@ __all__ = [
     "ContainerStartError",
     "DbConnInfo",
     "DockerNotRunningError",
+    "NameTemplateError",
     "PytestTestcontainersError",
     "ReuseConflictError",
     "make_container",
@@ -34,4 +36,4 @@ __all__ = [
     "make_redis",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.2"

pytest_testcontainers-0.2.2/src/pytest_testcontainers/_internal/docker_health.py

@@ -0,0 +1,105 @@
+"""Docker daemon health check — single source of truth for daemon ping.
+
+The cache stores **only successful pings**. A successful ping flips a
+process-wide flag; subsequent maker calls in the same process skip the
+probe. A failed ping does NOT poison the cache, so a transient daemon
+restart inside a long-running pytest session does not permanently
+disable the plugin.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+
+from pytest_testcontainers.errors import DockerNotRunningError
+
+logger = logging.getLogger("pytest_testcontainers")
+
+_lock = threading.Lock()
+_ping_ok: bool = False
+
+
+def _is_truthy(value: str | None) -> bool:
+    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def reset_cache() -> None:
+    """Reset the success cache. Used in tests."""
+    global _ping_ok
+    with _lock:
+        _ping_ok = False
+
+
+def ensure_docker_host_env() -> None:
+    """Export ``DOCKER_HOST`` from the active ``docker context`` when unset.
+
+    ``docker.from_env()`` — used by docker-py, by testcontainers' own client,
+    and by Ryuk's socket bind-mount — honors ``DOCKER_HOST`` but, unlike the
+    ``docker`` CLI, ignores the active ``docker context``. On OrbStack /
+    colima / a stopped Docker Desktop the daemon lives on a non-default socket
+    and ``/var/run/docker.sock`` is absent or a dangling symlink, so container
+    launch crashes with ``FileNotFoundError`` even though ``docker ps`` works.
+
+    Exporting ``DOCKER_HOST`` once — before any client is built — makes the
+    whole process resolve Docker the way the CLI does. No-op when
+    ``DOCKER_HOST`` is already set (an explicit choice always wins) or when no
+    context endpoint resolves (fall back to the platform default socket).
+    """
+    if os.environ.get("DOCKER_HOST"):
+        return
+    ctx = _active_docker_context()
+    host = getattr(ctx, "Host", None) if ctx is not None else None
+    if host:
+        os.environ["DOCKER_HOST"] = host
+
+
+def _active_docker_context():  # type: ignore[no-untyped-def]
+    """Return the active ``docker context`` object, or ``None``.
+
+    Resolution failures (older SDK without context support, malformed
+    ``~/.docker/config.json``, missing context) are logged and swallowed so
+    the caller falls back to the platform default socket.
+    """
+    try:
+        from docker.context import ContextAPI
+
+        return ContextAPI.get_current_context()
+    except Exception:
+        logger.debug("could not resolve active docker context", exc_info=True)
+        return None
+
+
+def check_docker_daemon() -> None:
+    """Ping the Docker daemon once per process (on success).
+
+    Raises :class:`DockerNotRunningError` (chained from the underlying
+    docker-py exception) if the daemon cannot be reached.
+    """
+    global _ping_ok
+    if _ping_ok:
+        return
+    # Honor the active `docker context` before any client (ours, testcontainers'
+    # or Ryuk's) is built — even when the ping itself is skipped, so the launch
+    # path still resolves the right socket on OrbStack / colima / Docker Desktop.
+    ensure_docker_host_env()
+    if _is_truthy(os.environ.get("PYTEST_TESTCONTAINERS_NO_DAEMON_CHECK")):
+        return
+
+    try:
+        import docker  # local import: never trigger at module-import time
+    except ImportError as exc:  # pragma: no cover — docker is a hard dep
+        raise DockerNotRunningError(
+            "docker-py is not installed; cannot ping Docker daemon"
+        ) from exc
+
+    try:
+        client = docker.from_env()
+        client.ping()
+    except Exception as exc:
+        # Surface the underlying daemon failure with a concrete cause.
+        raise DockerNotRunningError(f"docker.from_env().ping() failed: {exc!r}") from exc
+
+    with _lock:
+        _ping_ok = True

pytest_testcontainers-0.2.2/src/pytest_testcontainers/_internal/git_identity.py

@@ -0,0 +1,80 @@
+"""Filesystem-only git identity helpers: worktree root + current branch.
+
+Pure reads — no subprocess, no docker, no import-time side effects. Used by
+``reuse.py`` to compute the ``{branch}``, ``{dir}`` and ``{dirtag}`` name
+components. Handles both a normal clone (``.git`` is a directory) and a
+linked worktree (``.git`` is a file containing ``gitdir: <path>``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def worktree_root(start: Path) -> Path:
+    """Return the directory that owns the working tree containing ``start``.
+
+    Walks upward from ``start`` looking for a ``.git`` entry (a directory in a
+    normal clone, a file in a linked worktree — either marks the root). Falls
+    back to ``start.resolve()`` when no ``.git`` is found.
+    """
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".git").exists():
+            return candidate
+    return current
+
+
+def _gitdir_for(root: Path) -> Path | None:
+    """Resolve the gitdir that holds ``HEAD`` for the worktree at ``root``.
+
+    Normal clone: ``<root>/.git`` is a directory → that directory.
+    Linked worktree: ``<root>/.git`` is a file ``gitdir: <path>`` → ``<path>``
+    (resolved relative to ``root`` when the recorded path is relative).
+    Returns ``None`` when neither shape is readable.
+    """
+    dot_git = root / ".git"
+    if dot_git.is_dir():
+        return dot_git
+    if dot_git.is_file():
+        try:
+            content = dot_git.read_text(encoding="utf-8", errors="replace").strip()
+        except OSError:
+            return None
+        prefix = "gitdir:"
+        if content.startswith(prefix):
+            target = content[len(prefix) :].strip()
+            if target:
+                resolved = Path(target)
+                if not resolved.is_absolute():
+                    resolved = (root / resolved).resolve()
+                return resolved
+    return None
+
+
+def current_branch(start: Path) -> str | None:
+    """Return the current git branch name, or ``None``.
+
+    Reads ``HEAD`` from the resolved gitdir without spawning git:
+    - ``ref: refs/heads/<b>`` → ``<b>``
+    - any other ``ref: .../<x>`` → last path component ``<x>``
+    - raw SHA (detached HEAD) → first 12 chars
+    - unreadable / missing / empty → ``None``
+    """
+    root = worktree_root(start)
+    gitdir = _gitdir_for(root)
+    if gitdir is None:
+        return None
+    try:
+        content = (gitdir / "HEAD").read_text(encoding="utf-8", errors="replace").strip()
+    except OSError:
+        return None
+    if not content:
+        return None
+    if content.startswith("ref:"):
+        ref = content[len("ref:") :].strip()
+        marker = "refs/heads/"
+        if marker in ref:
+            return ref.split(marker, 1)[1] or None
+        return ref.rsplit("/", 1)[-1] or None
+    return content[:12]

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/src/pytest_testcontainers/errors.py

@@ -30,6 +30,14 @@ class ReuseConflictError(PytestTestcontainersError):
     """
 
 
+class NameTemplateError(PytestTestcontainersError):
+    """The configured container-name template referenced an unknown placeholder.
+
+    Raised at name-resolution time (during fixture/maker setup, before any
+    container starts). The message enumerates the valid placeholders.
+    """
+
+
 class CleanSessionFixtureError(PytestTestcontainersError):
     """A clean-session fixture failed to issue an admin command.
 

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/src/pytest_testcontainers/makers.py

@@ -27,8 +27,8 @@ from pytest_testcontainers.containers import (
     start_or_raise,
 )
 from pytest_testcontainers.reuse import (
+    container_name_for,
     is_reuse_enabled,
-    reuse_name_for,
     sanitize_component,
 )
 
@@ -76,7 +76,7 @@ def _make_generic(
     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
+    name = container_name_for(service_slug, override=reuse_name, reuse_mode=reuse_on)
 
     if reuse_on:
         disable_ryuk_once()
@@ -84,7 +84,7 @@ def _make_generic(
     instance: DockerContainer | None = None
     is_bound_to_existing = False
 
-    if reuse_on and name is not None:
+    if reuse_on:
         existing = find_existing_container(name)
         if existing is not None:
             status = getattr(existing, "status", "")
@@ -106,8 +106,7 @@ def _make_generic(
 
     if instance is None:
         instance = container_cls(*constructor_args, **constructor_kwargs)
-        if name is not None:
-            instance.with_name(name)
+        instance.with_name(name)
         _apply_env(instance, env)
 
         image_for_msg = constructor_kwargs.get("image") or (

{pytest_testcontainers-0.2.0 → pytest_testcontainers-0.2.2}/src/pytest_testcontainers/plugin.py

@@ -50,6 +50,16 @@ def pytest_addoption(parser: pytest.Parser) -> None:
         dest="testcontainers_project",
         help="Override project name used in reuse-name prefix.",
     )
+    group.addoption(
+        "--testcontainers-name-template",
+        action="store",
+        default=None,
+        dest="testcontainers_name_template",
+        help=(
+            "Template for container names. Placeholders: {project} {service} "
+            "{branch} {dir} {dirtag} {worker} {rand}."
+        ),
+    )
     group.addoption(
         "--testcontainers-clean",
         action="store_true",
@@ -65,6 +75,9 @@ def pytest_configure(config: pytest.Config) -> None:
     project = config.getoption("testcontainers_project")
     if project:
         reuse.set_cli_project(project)
+    name_template = config.getoption("testcontainers_name_template")
+    if name_template:
+        reuse.set_cli_name_template(name_template)
     if config.getoption("testcontainers_no_reuse"):
         reuse.set_cli_reuse(False)
     elif config.getoption("testcontainers_reuse"):
@@ -82,6 +95,11 @@ def pytest_cmdline_main(config: pytest.Config) -> int | None:
     except ImportError:
         sys.stderr.write("[pytest-testcontainers] docker-py not installed\n")
         return 1
+    # Honor the active `docker context` (OrbStack / colima / Docker Desktop)
+    # before from_env(), same as the launch path.
+    from pytest_testcontainers._internal.docker_health import ensure_docker_host_env
+
+    ensure_docker_host_env()
     try:
         client = docker.from_env()
         client.ping()