release: v0.9.3 [skip ci]

.gitea/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
           PYTHONPATH: src
         run: |
           . .venv/bin/activate
-          python3 -m devx.tools.check_test_speed --max-seconds 60
+          python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5
       - name: Documentation coverage check
         env:
           PYTHONPATH: src

.taskid

@@ -1 +1 @@
-DEVX-12
+DEVX-23

CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.9.3] - 2026-06-24
+
+### Bug Fixes
+
+- Use tempfile for dockerd log to fix CI permission error
+
+## [0.9.2] - 2026-06-24
+
+### Bug Fixes
+
+- Use vfs storage driver for Docker-in-Docker in CI
+
+## [0.9.1] - 2026-06-23
+
+### Bug Fixes
+
+- Always start dockerd in CI runner for molecule tests
+
+## [0.9.0] - 2026-06-23
+
+### Features
+
+- Extract Docker daemon start to tested Python module
+
+## [0.8.5] - 2026-06-23
+
+### Bug Fixes
+
+- Retry pip install with --ignore-installed only on failure
+
+## [0.8.4] - 2026-06-23
+
+### Bug Fixes
+
+- Add --ignore-installed to pip in CI to bypass debian packages
+
+## [0.8.3] - 2026-06-23
+
+### Bug Fixes
+
+- Lower check_test_speed threshold to 4 seconds
+- Pass --break-system-packages to pip in CI environments
+
+## [0.8.2] - 2026-06-23
+
+### Bug Fixes
+
+- Encode spaces in pair commands to survive shell word-splitting
+
+## [0.8.1] - 2026-06-23
+
+### Bug Fixes
+
+- Set fresh MOLECULE_HOME per pair to avoid stale config cache
+
+## [0.8.0] - 2026-06-23
+
+### Features
+
+- Fix molecule platforms to use sleep infinity, add --platforms-file
+
+## [0.7.0] - 2026-06-23
+
+### Features
+
+- Add per-test timing quality gate to check_test_speed
+
 ## [0.6.0] - 2026-06-23
 
 ### Features

docs/user/cli-commands.md

@@ -76,7 +76,13 @@ Validate commit messages for conventional commit format.
 
 ### `devx tools check-test-speed`
 
-Run unit tests and enforce a maximum execution-time budget.
+Run unit tests and enforce execution-time budgets:
+- **Total suite time** must not exceed `--max-seconds` (default: 10s).
+- **Per-test time** — no individual test may exceed `--max-single-seconds` (default: 0.5s, 0 to disable).
+
+```bash
+python3 -m devx.tools.check_test_speed --max-seconds 10 --max-single-seconds 0.5
+```
 
 ### `devx tools configure-repo`
 

hooks/pre-commit

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# pre-commit hook: fail if unit tests take longer than 10 seconds.
-# Aligned with CI timeout (ci.yml uses --max-seconds 10).
+# pre-commit hook: fail if unit tests are too slow.
+# Checks both total suite time (10s) and per-test time (0.5s).
+# Aligned with CI (ci.yml uses same thresholds).
 set -e
 export PYTHONPATH=src
-python3 -m devx.tools.check_test_speed --max-seconds 10
+python3 -m devx.tools.check_test_speed --max-seconds 4 --max-single-seconds 0.5

src/devx/__init__.py

@@ -1,3 +1,3 @@
 """devx — reusable development and CI/CD tools for oblachno-oss projects."""
 
-__version__ = "0.6.0"
+__version__ = "0.9.3"

src/devx/molecule/distribute_molecule.py

@@ -25,7 +25,7 @@ from pathlib import Path
 import click
 
 from devx.i18n import _
-from devx.molecule.platforms import PLATFORMS
+from devx.molecule.platforms import PLATFORMS, load_platforms
 
 DEFAULT_MAX_RUNNERS = 3
 MOLECULE_ROOT = Path("ansible/roles/gitea-runner/molecule")
@@ -41,7 +41,8 @@ class TestPair:
 
     def encode(self) -> str:
         """Serialize to a pipe-delimited string for CI consumption."""
-        return f"{self.scenario}|{self.platform['name']}|{self.platform['image']}|{self.platform['command']}"
+        cmd = self.platform["command"].replace(" ", "__SPACE__")
+        return f"{self.scenario}|{self.platform['name']}|{self.platform['image']}|{cmd}"
 
     @staticmethod
     def decode(encoded: str) -> TestPair:
@@ -49,7 +50,7 @@ class TestPair:
         parts = encoded.split("|")
         return TestPair(
             scenario=parts[0],
-            platform={"name": parts[1], "image": parts[2], "command": parts[3]},
+            platform={"name": parts[1], "image": parts[2], "command": parts[3].replace("__SPACE__", " ")},
         )
 
 
@@ -63,9 +64,8 @@ class MultiRoleTestPair:
 
     def encode(self) -> str:
         """Serialize to a pipe-delimited string: ``role|scenario|platform_name|image|command``."""
-        return (
-            f"{self.role}|{self.scenario}|{self.platform['name']}|{self.platform['image']}|{self.platform['command']}"
-        )
+        cmd = self.platform["command"].replace(" ", "__SPACE__")
+        return f"{self.role}|{self.scenario}|{self.platform['name']}|{self.platform['image']}|{cmd}"
 
     @staticmethod
     def decode(encoded: str) -> MultiRoleTestPair:
@@ -74,7 +74,7 @@ class MultiRoleTestPair:
         return MultiRoleTestPair(
             role=parts[0],
             scenario=parts[1],
-            platform={"name": parts[2], "image": parts[3], "command": parts[4]},
+            platform={"name": parts[2], "image": parts[3], "command": parts[4].replace("__SPACE__", " ")},
         )
 
 
@@ -238,6 +238,13 @@ def _write_github_env(key: str, value: str) -> None:
     help="Roles directory for multi-role discovery (scans */molecule/*/). "
     "Use this for projects with multiple Ansible roles. Default: disabled (single-role mode).",
 )
+@click.option(
+    "--platforms-file",
+    type=click.Path(exists=True, file_okay=True, path_type=Path),
+    default=None,
+    help="JSON file with custom platform list (each entry: name, image, command). "
+    "Overrides the default platform matrix. Useful for projects with custom test images.",
+)
 def cli(
     runner_index: int | None,
     max_runners: int,
@@ -247,7 +254,9 @@ def cli(
     skip_if_excess: bool,
     molecule_root: Path | None,
     roles_root: Path | None,
+    platforms_file: Path | None,
 ) -> None:
+    platforms = load_platforms(platforms_file)
     # Multi-role mode: discover (role, scenario) pairs across all roles
     if roles_root is not None:
         role_scenarios = discover_multi_role_scenarios(roles_root)
@@ -256,10 +265,10 @@ def cli(
                 click.echo(f"{role}|{scenario}")
             return
         if list_platforms:
-            for p in PLATFORMS:
+            for p in platforms:
                 click.echo(f"{p['name']}|{p['image']}|{p['command']}")
             return
-        pairs_mr = build_multi_role_pairs(role_scenarios)
+        pairs_mr = build_multi_role_pairs(role_scenarios, platforms)
         if runner_index is None:
             groups = distribute_multi_role(pairs_mr, max_runners)
             for i, group in enumerate(groups):
@@ -291,10 +300,10 @@ def cli(
             click.echo(s)
         return
     if list_platforms:
-        for p in PLATFORMS:
+        for p in platforms:
             click.echo(f"{p['name']}|{p['image']}|{p['command']}")
         return
-    pairs = build_pairs(scenarios)
+    pairs = build_pairs(scenarios, platforms)
     if runner_index is None:
         groups = distribute(pairs, max_runners)
         for i, group in enumerate(groups):

src/devx/molecule/molecule_ci_guard.py

@@ -114,12 +114,14 @@ def parse_pair(pair: str) -> tuple[str, str, str, str, str]:
 
     Supports both 4-part (single-role) and 5-part (multi-role) formats.
     For 4-part pairs, role is empty (caller uses default role dir).
+    Spaces in the command field are encoded as ``__SPACE__`` to survive
+    shell word-splitting when ``$TEST_PAIRS`` is expanded unquoted.
     """
     parts = pair.split("|")
     if len(parts) == 4:
-        return "", parts[0], parts[1], parts[2], parts[3]
+        return "", parts[0], parts[1], parts[2], parts[3].replace("__SPACE__", " ")
     if len(parts) == 5:
-        return parts[0], parts[1], parts[2], parts[3], parts[4]
+        return parts[0], parts[1], parts[2], parts[3], parts[4].replace("__SPACE__", " ")
     raise click.ClickException(f"Invalid pair format: {pair!r} (expected 4 or 5 pipe-delimited parts)")
 
 
@@ -134,6 +136,12 @@ def build_env_for_pair(pair: str, base_env: dict[str, str]) -> dict[str, str]:
     elif "MOLECULE_PLATFORM_COMMAND" in env:
         del env["MOLECULE_PLATFORM_COMMAND"]
     env["ANSIBLE_ALLOW_BROKEN_CONDITIONALS"] = "true"
+    # Use a fresh MOLECULE_HOME per pair to avoid stale config cache
+    # from previous CI runs (causes "Instances missing" errors).
+    if "MOLECULE_HOME" not in env:
+        import tempfile
+
+        env["MOLECULE_HOME"] = tempfile.mkdtemp(prefix="molecule-ci-")
     return env
 
 

src/devx/molecule/platforms.py

@@ -10,13 +10,39 @@ dev tools and CI scripts.
 
 from __future__ import annotations
 
-#: Supported OS platform matrix.
+import json
+from pathlib import Path
+
+#: Default supported OS platform matrix.
 #: Each entry maps a short name to (image, command).
-#: The command must be systemd since rootless Docker requires
-#: loginctl/systemctl --user.
+#: Uses the project's pre-built molecule-test-base image with
+#: ``sleep infinity`` (NOT systemd) to avoid cgroup v2 failures.
 PLATFORMS: list[dict[str, str]] = [
-    {"name": "ubuntu-2204", "image": "geerlingguy/docker-ubuntu2204-ansible:latest", "command": "/lib/systemd/systemd"},
-    {"name": "ubuntu-2404", "image": "geerlingguy/docker-ubuntu2404-ansible:latest", "command": "/lib/systemd/systemd"},
-    {"name": "debian-12", "image": "geerlingguy/docker-debian12-ansible:latest", "command": "/lib/systemd/systemd"},
-    {"name": "archlinux", "image": "marcstraube/archlinux-ansible:latest", "command": "/usr/lib/systemd/systemd"},
+    {
+        "name": "ubuntu-2604",
+        "image": "git.oblachno.oblachno.fyi/oblachno/molecule-test-base:latest",
+        "command": "sleep infinity",
+    },
 ]
+
+
+def load_platforms(platforms_file: str | Path | None = None) -> list[dict[str, str]]:
+    """Load platforms from a JSON file, falling back to PLATFORMS.
+
+    Args:
+        platforms_file: Path to a JSON file with a list of platform dicts.
+            Each dict must have ``name``, ``image``, and ``command`` keys.
+
+    Returns:
+        List of platform dictionaries.
+    """
+    if platforms_file is None:
+        return PLATFORMS
+    path = Path(platforms_file)
+    if not path.is_file():
+        return PLATFORMS
+    with path.open() as f:
+        data = json.load(f)
+    if not isinstance(data, list) or not data:
+        return PLATFORMS
+    return data

src/devx/molecule/start_docker.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Start a Docker daemon inside a CI runner container (Docker-in-Docker).
+
+CI runners (e.g. ``gitea/runner-images:ubuntu-latest``) may have the host's
+Docker socket mounted, but molecule needs a local Docker daemon to create
+nested containers. This module always starts ``dockerd`` in the background
+and waits for it to become ready.
+
+Usage::
+
+    python3 -m devx.molecule.start_docker [--timeout 30]
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+import tempfile
+import time
+
+import click
+
+from devx.i18n import _
+
+DEFAULT_TIMEOUT = 30
+
+
+def is_docker_ready() -> bool:
+    """Check if the Docker daemon is responding."""
+    result = subprocess.run(  # nosec B603 B607
+        ["docker", "info"],
+        capture_output=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def start_docker_daemon(timeout: int = DEFAULT_TIMEOUT) -> bool:
+    """Start dockerd in the background and wait for it to be ready.
+
+    Always starts a local dockerd even if ``docker info`` succeeds,
+    because the host socket may be mounted but not suitable for
+    molecule's nested container creation.
+
+    Returns ``True`` if Docker is ready, ``False`` if it failed to
+    start within the timeout.
+    """
+    click.echo(_("Starting Docker daemon..."))
+    log_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
+        mode="w", suffix="dockerd.log", delete=False
+    )
+    subprocess.Popen(  # nosec B603 B607
+        ["dockerd", "--storage-driver", "vfs"],
+        stdout=log_file,
+        stderr=subprocess.STDOUT,
+        start_new_session=True,
+    )
+
+    for _i in range(timeout):
+        if is_docker_ready():
+            click.echo(_("Docker daemon started"))
+            return True
+        time.sleep(1)
+
+    click.echo(_("Docker daemon failed to start"))
+    return False
+
+
+@click.command()
+@click.option(
+    "--timeout",
+    default=DEFAULT_TIMEOUT,
+    type=int,
+    help="Seconds to wait for Docker daemon to start (default: 30).",
+)
+def main(timeout: int) -> None:
+    """Start Docker daemon for CI molecule tests."""
+    if start_docker_daemon(timeout):
+        sys.exit(0)
+    sys.exit(1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

src/devx/tools/check_test_speed.py

@@ -1,12 +1,21 @@
 #!/usr/bin/env python3
-"""Run unit tests and enforce a maximum execution-time budget.
+"""Run unit tests and enforce execution-time budgets.
+
+Checks two quality gates:
+1. **Total suite time** must not exceed ``--max-seconds``.
+2. **Per-test time** — no individual test may exceed ``--max-single-seconds``.
 
 Usage:
-  python3 -m devx.tools.check_test_speed [--max-seconds N]
+  python3 -m devx.tools.check_test_speed [--max-seconds N] [--max-single-seconds S]
+
+The module runs ``make test-unit`` with ``PYTEST_ADDOPTS=--durations=0`` so
+that pytest emits per-test timing lines alongside the summary.  Both the
+total wall-clock time and individual test durations are parsed and validated.
 """
 
 from __future__ import annotations
 
+import os
 import re
 import subprocess  # nosec B404
 
@@ -14,18 +23,32 @@ import click
 
 from devx.i18n import _
 
-DEFAULT_MAX_SECONDS = 2.0
+DEFAULT_MAX_SECONDS = 10.0
+DEFAULT_MAX_SINGLE_SECONDS = 0.5
 TEST_COMMAND = ["make", "test-unit"]
+
+# Matches pytest summary line: "234 passed in 0.70s"
 _TIMING_RE = re.compile(r"(\d+) passed.* in ([0-9.]+)s")
 
+# Matches per-test duration lines from --durations=0:
+#   0.51s call     tests/test_foo.py::test_bar
+_DURATION_LINE_RE = re.compile(r"^(\d+\.?\d*)s\s+(?:setup|call|teardown)\s+(.+)$")
+
 
 def run_tests() -> tuple[str, str]:
-    """Execute the unit-test suite and return (stdout, stderr)."""
+    """Execute the unit-test suite and return (stdout, stderr).
+
+    Sets ``PYTEST_ADDOPTS=--durations=0`` so pytest emits per-test timings.
+    """
+    env = os.environ.copy()
+    existing = env.get("PYTEST_ADDOPTS", "")
+    env["PYTEST_ADDOPTS"] = f"--durations=0 {existing}".strip()
     result = subprocess.run(  # nosec B603
         TEST_COMMAND,
         capture_output=True,
         text=True,
         check=False,
+        env=env,
     )
     return result.stdout, result.stderr
 
@@ -43,8 +66,23 @@ def parse_duration(output: str) -> float:
     raise click.ClickException(_("Could not parse test execution time from output."))
 
 
+def parse_per_test_durations(output: str) -> list[tuple[str, float]]:
+    """Extract per-test timings from ``--durations=0`` output.
+
+    Returns a list of ``(test_name, seconds)`` tuples sorted by duration
+    (slowest first).
+    """
+    durations: list[tuple[str, float]] = []
+    for line in output.splitlines():
+        match = _DURATION_LINE_RE.match(line.strip())
+        if match:
+            durations.append((match.group(2).strip(), float(match.group(1))))
+    durations.sort(key=lambda x: x[1], reverse=True)
+    return durations
+
+
 def check_speed(duration: float, max_seconds: float) -> None:
-    """Validate duration is within budget; raise on violation."""
+    """Validate total duration is within budget; raise on violation."""
     if duration > max_seconds:
         raise click.ClickException(
             _(
@@ -57,19 +95,58 @@ def check_speed(duration: float, max_seconds: float) -> None:
         )
 
 
-def main(max_seconds: float) -> None:
-    """Run tests, parse timing, and enforce the budget."""
+def check_per_test_speed(
+    durations: list[tuple[str, float]],
+    max_single_seconds: float,
+) -> list[str]:
+    """Return a list of violation messages for tests exceeding the per-test limit.
+
+    An empty list means all tests are within budget.
+    """
+    violations: list[str] = []
+    for name, elapsed in durations:
+        if elapsed > max_single_seconds:
+            violations.append(
+                _(
+                    "Test '{name}' took {elapsed:.2f}s (limit: {limit}s). "
+                    "Optimise: use lighter fixtures, reduce I/O, or mock external calls.",
+                    name=name,
+                    elapsed=elapsed,
+                    limit=max_single_seconds,
+                )
+            )
+    return violations
+
+
+def main(max_seconds: float, max_single_seconds: float) -> None:
+    """Run tests, parse timings, and enforce both budgets."""
     stdout, stderr = run_tests()
     combined = stdout + "\n" + stderr
     click.echo(combined, err=False)
 
     duration = parse_duration(combined)
     check_speed(duration, max_seconds)
+
+    if max_single_seconds > 0:
+        per_test = parse_per_test_durations(combined)
+        violations = check_per_test_speed(per_test, max_single_seconds)
+        if violations:
+            msg = _(
+                "Per-test speed check FAILED: {count} test(s) exceed {limit}s limit.",
+                count=len(violations),
+                limit=max_single_seconds,
+            )
+            click.echo(f"\n{msg}", err=True)
+            for v in violations:
+                click.echo(f"  - {v}", err=True)
+            raise click.ClickException(msg)
+
     click.echo(
         _(
-            "Unit tests passed in {duration:.2f}s (under {max}s limit).",
+            "Unit tests passed in {duration:.2f}s (under {max}s limit, all tests under {single}s per-test limit).",
             duration=duration,
             max=max_seconds,
+            single=max_single_seconds,
         )
     )
 
@@ -80,10 +157,17 @@ def main(max_seconds: float) -> None:
     type=float,
     default=DEFAULT_MAX_SECONDS,
     show_default=True,
-    help="Maximum allowed execution time in seconds.",
+    help="Maximum allowed total execution time in seconds.",
 )
-def cli(max_seconds: float) -> None:
-    main(max_seconds)
+@click.option(
+    "--max-single-seconds",
+    type=float,
+    default=DEFAULT_MAX_SINGLE_SECONDS,
+    show_default=True,
+    help="Maximum allowed per-test time in seconds (0 to disable).",
+)
+def cli(max_seconds: float, max_single_seconds: float) -> None:
+    main(max_seconds, max_single_seconds)
 
 
 if __name__ == "__main__":  # pragma: no cover

src/devx/tools/setup.py

@@ -26,9 +26,24 @@ def _run(cmd: list[str]) -> None:
 
 
 def _install_python_deps(bin_dir: str, extras: str = "dev") -> None:
-    """Install the project with the specified extras in editable mode."""
+    """Install the project with the specified extras in editable mode.
+
+    In CI (system Python with PIP_BREAK_SYSTEM_PACKAGES=1), a first attempt
+    uses --break-system-packages. If that fails (e.g. debian-installed
+    packages without RECORD files), retry with --ignore-installed to skip
+    uninstalling system packages entirely.
+    """
     pip = str(Path(bin_dir) / "pip")
-    _run([pip, "install", "-e", f".[{extras}]"])
+    cmd = [pip, "install", "-e", f".[{extras}]"]
+    if os.environ.get("PIP_BREAK_SYSTEM_PACKAGES") == "1":
+        cmd.append("--break-system-packages")
+    result = subprocess.run(cmd, check=False)  # nosec B603
+    if result.returncode != 0 and os.environ.get("PIP_BREAK_SYSTEM_PACKAGES") == "1":
+        click.echo("  Retrying with --ignore-installed to bypass system packages...")
+        cmd.append("--ignore-installed")
+        _run(cmd)
+    elif result.returncode != 0:
+        raise subprocess.CalledProcessError(result.returncode, cmd)
 
 
 def _install_pre_commit_hooks(bin_dir: str) -> None:
@@ -40,7 +55,7 @@ def _install_pre_commit_hooks(bin_dir: str) -> None:
 
 def _install_ansible_collections(bin_dir: str) -> None:
     """Install required Ansible Galaxy collections if requirements exist."""
-    galaxy = str(Path(bin_dir) / "ansible-galaxy")
+    galaxy = shutil.which("ansible-galaxy") or str(Path(bin_dir) / "ansible-galaxy")
     requirements = Path("ansible/requirements.yml")
     if not requirements.exists():
         click.echo("  ansible/requirements.yml not found — skipping collections.")

tests/unit/test_api_clients.py

@@ -566,7 +566,8 @@ class TestVikunjaClient:
             json={"done": True},
         )
 
-    def test_http_error_raises_api_error(self) -> None:
+    @patch("devx.api_clients.time.sleep")
+    def test_http_error_raises_api_error(self, mock_sleep: MagicMock) -> None:
         client = VikunjaClient("https://work.example.com", "tok")
         mock_resp = MagicMock()
         mock_resp.raise_for_status.side_effect = _mock_http_error(http.HTTPStatus.INTERNAL_SERVER_ERROR, "server error")

tests/unit/test_check_test_speed.py

@@ -1,4 +1,4 @@
-"""Unit tests for scripts/check_test_speed.py."""
+"""Unit tests for devx.tools.check_test_speed."""
 
 from unittest.mock import MagicMock, patch
 
@@ -8,10 +8,13 @@ from click.testing import CliRunner
 
 from devx.tools.check_test_speed import (
     DEFAULT_MAX_SECONDS,
+    DEFAULT_MAX_SINGLE_SECONDS,
     TEST_COMMAND,
+    check_per_test_speed,
     check_speed,
     cli,
     parse_duration,
+    parse_per_test_durations,
     run_tests,
 )
 
@@ -23,12 +26,23 @@ class TestRunTests:
         stdout, stderr = run_tests()
         assert stdout == "out"
         assert stderr == "err"
-        mock_run.assert_called_once_with(
-            TEST_COMMAND,
-            capture_output=True,
-            text=True,
-            check=False,
-        )
+        mock_run.assert_called_once()
+        call_kwargs = mock_run.call_args
+        assert call_kwargs.args[0] == TEST_COMMAND
+        assert call_kwargs.kwargs["capture_output"] is True
+        assert call_kwargs.kwargs["text"] is True
+        assert call_kwargs.kwargs["check"] is False
+        env = call_kwargs.kwargs["env"]
+        assert "--durations=0" in env["PYTEST_ADDOPTS"]
+
+    @patch("devx.tools.check_test_speed.subprocess.run")
+    def test_run_tests_preserves_existing_pytest_addopts(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(stdout="out", stderr="err", returncode=0)
+        with patch.dict("os.environ", {"PYTEST_ADDOPTS": "-x"}, clear=False):
+            run_tests()
+        env = mock_run.call_args.kwargs["env"]
+        assert "--durations=0" in env["PYTEST_ADDOPTS"]
+        assert "-x" in env["PYTEST_ADDOPTS"]
 
 
 class TestParseDuration:
@@ -48,6 +62,38 @@ class TestParseDuration:
         assert "Could not parse" in str(exc.value)
 
 
+class TestParsePerTestDurations:
+    def test_parses_call_lines(self) -> None:
+        output = "0.01s call     tests/test_foo.py::test_bar\n"
+        durations = parse_per_test_durations(output)
+        assert len(durations) == 1
+        assert durations[0] == ("tests/test_foo.py::test_bar", 0.01)
+
+    def test_parses_setup_and_teardown(self) -> None:
+        output = (
+            "0.02s setup    tests/test_foo.py::test_bar\n"
+            "0.01s call     tests/test_foo.py::test_bar\n"
+            "0.00s teardown tests/test_foo.py::test_bar\n"
+        )
+        durations = parse_per_test_durations(output)
+        assert len(durations) == 3
+        names = [d[0] for d in durations]
+        assert "tests/test_foo.py::test_bar" in names
+
+    def test_sorted_slowest_first(self) -> None:
+        output = "0.01s call     tests/test_a.py::test_slow\n0.50s call     tests/test_b.py::test_fast\n"
+        durations = parse_per_test_durations(output)
+        assert durations[0][1] >= durations[1][1]
+        assert durations[0][1] == 0.50
+
+    def test_empty_output(self) -> None:
+        assert parse_per_test_durations("") == []
+
+    def test_ignores_non_duration_lines(self) -> None:
+        output = "Some random line\n234 passed in 0.70s\n"
+        assert parse_per_test_durations(output) == []
+
+
 class TestCheckSpeed:
     def test_under_budget_passes(self) -> None:
         check_speed(1.0, 2.0)  # should not raise
@@ -64,6 +110,31 @@ class TestCheckSpeed:
         assert "max allowed: 2.0s" in msg
 
 
+class TestCheckPerTestSpeed:
+    def test_no_violations_when_all_fast(self) -> None:
+        durations = [("test_a", 0.1), ("test_b", 0.2)]
+        assert check_per_test_speed(durations, 0.5) == []
+
+    def test_violation_when_test_exceeds_limit(self) -> None:
+        durations = [("test_slow", 0.6), ("test_fast", 0.1)]
+        violations = check_per_test_speed(durations, 0.5)
+        assert len(violations) == 1
+        assert "test_slow" in violations[0]
+        assert "0.60s" in violations[0]
+
+    def test_multiple_violations(self) -> None:
+        durations = [("test_a", 0.7), ("test_b", 0.6), ("test_c", 0.1)]
+        violations = check_per_test_speed(durations, 0.5)
+        assert len(violations) == 2
+
+    def test_exact_limit_passes(self) -> None:
+        durations = [("test_a", 0.5)]
+        assert check_per_test_speed(durations, 0.5) == []
+
+    def test_empty_durations(self) -> None:
+        assert check_per_test_speed([], 0.5) == []
+
+
 def test_main_module_block() -> None:
     import devx.tools.check_test_speed as cts
 
@@ -77,39 +148,71 @@ class TestMain:
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
     def test_successful_run(
         self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
         mock_check: MagicMock,
         mock_parse: MagicMock,
         mock_run: MagicMock,
     ) -> None:
         mock_run.return_value = ("stdout\n", "stderr\n")
         mock_parse.return_value = 1.5
+        mock_parse_per.return_value = []
+        mock_check_per.return_value = []
 
         runner = CliRunner()
         result = runner.invoke(cli, [])
         assert result.exit_code == 0
         assert "1.50s" in result.output
-        assert "under 2.0s limit" in result.output
+        assert "under 10.0s limit" in result.output
         mock_run.assert_called_once()
         mock_parse.assert_called_once_with("stdout\n\nstderr\n")
         mock_check.assert_called_once_with(1.5, DEFAULT_MAX_SECONDS)
+        mock_parse_per.assert_called_once()
+        mock_check_per.assert_called_once_with([], DEFAULT_MAX_SINGLE_SECONDS)
 
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
-    def test_slow_tests_exit(
+    def test_slow_total_exits(
         self,
         mock_parse: MagicMock,
         mock_run: MagicMock,
     ) -> None:
         mock_run.return_value = ("out\n", "err\n")
-        mock_parse.return_value = 3.0
+        mock_parse.return_value = 15.0
 
         runner = CliRunner()
         result = runner.invoke(cli, [])
         assert result.exit_code == 1
         assert "too slow" in result.output.lower()
 
+    @patch("devx.tools.check_test_speed.run_tests")
+    @patch("devx.tools.check_test_speed.parse_duration")
+    @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
+    def test_per_test_violation_exits(
+        self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
+        mock_check: MagicMock,
+        mock_parse: MagicMock,
+        mock_run: MagicMock,
+    ) -> None:
+        mock_run.return_value = ("out\n", "err\n")
+        mock_parse.return_value = 3.0
+        mock_parse_per.return_value = [("test_slow", 0.8)]
+        mock_check_per.return_value = ["Test 'test_slow' took 0.80s (limit: 0.5s)."]
+
+        runner = CliRunner()
+        result = runner.invoke(cli, [])
+        assert result.exit_code == 1
+        assert "Per-test speed check FAILED" in result.output
+        assert "test_slow" in result.output
+
     @patch("devx.tools.check_test_speed.run_tests")
     def test_parse_failure_exits(
         self,
@@ -125,16 +228,67 @@ class TestMain:
     @patch("devx.tools.check_test_speed.run_tests")
     @patch("devx.tools.check_test_speed.parse_duration")
     @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
     def test_custom_max_seconds(
         self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
         mock_check: MagicMock,
         mock_parse: MagicMock,
         mock_run: MagicMock,
     ) -> None:
         mock_run.return_value = ("out\n", "err\n")
         mock_parse.return_value = 0.5
+        mock_parse_per.return_value = []
+        mock_check_per.return_value = []
 
         runner = CliRunner()
         result = runner.invoke(cli, ["--max-seconds", "1.5"])
         assert result.exit_code == 0
         mock_check.assert_called_once_with(0.5, 1.5)
+
+    @patch("devx.tools.check_test_speed.run_tests")
+    @patch("devx.tools.check_test_speed.parse_duration")
+    @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
+    def test_disable_per_test_check(
+        self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
+        mock_check: MagicMock,
+        mock_parse: MagicMock,
+        mock_run: MagicMock,
+    ) -> None:
+        mock_run.return_value = ("out\n", "err\n")
+        mock_parse.return_value = 1.0
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--max-single-seconds", "0"])
+        assert result.exit_code == 0
+        mock_parse_per.assert_not_called()
+        mock_check_per.assert_not_called()
+
+    @patch("devx.tools.check_test_speed.run_tests")
+    @patch("devx.tools.check_test_speed.parse_duration")
+    @patch("devx.tools.check_test_speed.check_speed")
+    @patch("devx.tools.check_test_speed.parse_per_test_durations")
+    @patch("devx.tools.check_test_speed.check_per_test_speed")
+    def test_custom_max_single_seconds(
+        self,
+        mock_check_per: MagicMock,
+        mock_parse_per: MagicMock,
+        mock_check: MagicMock,
+        mock_parse: MagicMock,
+        mock_run: MagicMock,
+    ) -> None:
+        mock_run.return_value = ("out\n", "err\n")
+        mock_parse.return_value = 1.0
+        mock_parse_per.return_value = []
+        mock_check_per.return_value = []
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--max-single-seconds", "1.0"])
+        assert result.exit_code == 0
+        mock_check_per.assert_called_once_with([], 1.0)

tests/unit/test_distribute_molecule.py

@@ -163,10 +163,7 @@ class TestCli:
             runner = CliRunner()
             result = runner.invoke(cli, ["--list-platforms"])
         assert result.exit_code == 0
-        assert "ubuntu-2204" in result.output
-        assert "ubuntu-2404" in result.output
-        assert "debian-12" in result.output
-        assert "archlinux" in result.output
+        assert "ubuntu-2604" in result.output
 
     def test_no_runner_index_prints_all_groups(self, tmp_path: Path) -> None:
         from click.testing import CliRunner
@@ -198,7 +195,7 @@ class TestCli:
             assert result.exit_code == 0
             # Output should contain encoded pairs with platform info
             assert "alpha|" in result.output
-            assert "ubuntu-2204" in result.output
+            assert "ubuntu-2604" in result.output
 
 
 class TestGithubEnv:
@@ -409,7 +406,7 @@ class TestCliMultiRole:
         runner = CliRunner()
         result = runner.invoke(cli, ["--roles-root", str(roles), "--list-platforms"])
         assert result.exit_code == 0
-        assert "ubuntu-2204" in result.output
+        assert "ubuntu-2604" in result.output
 
     def test_roles_root_no_runner_index_prints_groups(self, tmp_path: Path) -> None:
         """--roles-root without --runner-index prints all groups."""
@@ -422,6 +419,27 @@ class TestCliMultiRole:
         assert "Runner 0:" in result.output
         assert "Runner 1:" in result.output
 
+    def test_platforms_file_overrides_default(self, tmp_path: Path) -> None:
+        """--platforms-file loads custom platforms from JSON."""
+        import json
+
+        from click.testing import CliRunner
+
+        from devx.molecule.distribute_molecule import cli
+
+        roles = tmp_path / "roles"
+        (roles / "role-a" / "molecule" / "default").mkdir(parents=True)
+        platforms_file = tmp_path / "platforms.json"
+        custom = [{"name": "custom-os", "image": "custom:latest", "command": "sleep infinity"}]
+        platforms_file.write_text(json.dumps(custom))
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["--roles-root", str(roles), "--platforms-file", str(platforms_file), "--list-platforms"]
+        )
+        assert result.exit_code == 0
+        assert "custom-os" in result.output
+        assert "custom:latest" in result.output
+
     def test_roles_root_skips_non_dir_role(self, tmp_path: Path) -> None:
         """Non-directory entries in roles root are skipped."""
         roles = tmp_path / "roles"

tests/unit/test_integration_guard.py

@@ -131,6 +131,7 @@ class TestCli:
                 clear=True,
             ),
             patch("devx.ci.integration_guard.POLL_INTERVAL", 0.01),
+            patch("devx.molecule.molecule_ci_guard.POLL_INTERVAL", 0.01),
             patch("devx.ci.integration_guard.subprocess.Popen") as mock_popen,
             patch("devx.molecule.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg") as mock_killpg,
@@ -177,6 +178,7 @@ class TestCli:
                 clear=True,
             ),
             patch("devx.ci.integration_guard.POLL_INTERVAL", 0.01),
+            patch("devx.molecule.molecule_ci_guard.POLL_INTERVAL", 0.01),
             patch("devx.ci.integration_guard.subprocess.Popen") as mock_popen,
             patch("devx.molecule.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg", side_effect=ProcessLookupError("no such process")),
@@ -221,6 +223,7 @@ class TestCli:
                 clear=True,
             ),
             patch("devx.ci.integration_guard.POLL_INTERVAL", 0.01),
+            patch("devx.molecule.molecule_ci_guard.POLL_INTERVAL", 0.01),
             patch("devx.ci.integration_guard.subprocess.Popen") as mock_popen,
             patch("devx.molecule.molecule_ci_guard.get_running_jobs", side_effect=get_jobs_side_effect),
             patch("os.killpg") as mock_killpg,

tests/unit/test_platforms.py

@@ -1,11 +1,13 @@
-"""Unit tests for scripts/ci/platforms.py."""
+"""Unit tests for devx.molecule.platforms."""
 
-from devx.molecule.platforms import PLATFORMS
+import json
+
+from devx.molecule.platforms import PLATFORMS, load_platforms
 
 
 class TestPlatforms:
     def test_platforms_not_empty(self) -> None:
-        assert len(PLATFORMS) >= 4
+        assert len(PLATFORMS) >= 1
 
     def test_each_platform_has_required_keys(self) -> None:
         for p in PLATFORMS:
@@ -17,9 +19,40 @@ class TestPlatforms:
         names = [p["name"] for p in PLATFORMS]
         assert len(names) == len(set(names))
 
+    def test_platforms_use_sleep_infinity(self) -> None:
+        """All default platforms must use sleep infinity, not systemd."""
+        for p in PLATFORMS:
+            assert p["command"] == "sleep infinity", f"Platform {p['name']} uses {p['command']}"
+
     def test_known_platforms_present(self) -> None:
         names = {p["name"] for p in PLATFORMS}
-        assert "ubuntu-2204" in names
-        assert "ubuntu-2404" in names
-        assert "debian-12" in names
-        assert "archlinux" in names
+        assert "ubuntu-2604" in names
+
+
+class TestLoadPlatforms:
+    def test_load_platforms_default(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        """load_platforms with no file returns PLATFORMS."""
+        result = load_platforms(None)
+        assert result == PLATFORMS
+
+    def test_load_platforms_from_file(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        """load_platforms reads custom platforms from JSON file."""
+        custom = [
+            {"name": "custom-os", "image": "custom:latest", "command": "sleep infinity"},
+        ]
+        f = tmp_path / "platforms.json"
+        f.write_text(json.dumps(custom))
+        result = load_platforms(f)
+        assert result == custom
+
+    def test_load_platforms_missing_file_falls_back(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        """load_platforms falls back to PLATFORMS when file doesn't exist."""
+        result = load_platforms(tmp_path / "nonexistent.json")
+        assert result == PLATFORMS
+
+    def test_load_platforms_empty_list_falls_back(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        """load_platforms falls back to PLATFORMS when file has empty list."""
+        f = tmp_path / "platforms.json"
+        f.write_text("[]")
+        result = load_platforms(f)
+        assert result == PLATFORMS

tests/unit/test_setup.py

@@ -1,5 +1,6 @@
 """Unit tests for devx.tools.setup."""
 
+import os
 import subprocess
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -32,20 +33,48 @@ class TestRun:
 
 
 class TestInstallPythonDeps:
-    @patch("devx.tools.setup._run")
+    @patch("devx.tools.setup.subprocess.run")
     def test_install_dev(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0)
         _install_python_deps(".venv/bin", "dev")
-        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[dev]"])
+        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[dev]"], check=False)
 
-    @patch("devx.tools.setup._run")
+    @patch("devx.tools.setup.subprocess.run")
     def test_install_ci(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0)
         _install_python_deps(".venv/bin", "ci")
-        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[ci]"])
+        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[ci]"], check=False)
+
+    @patch("devx.tools.setup.subprocess.run")
+    def test_install_custom_extras(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0)
+        _install_python_deps(".venv/bin", "ci,lint")
+        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[ci,lint]"], check=False)
+
+    @patch("devx.tools.setup.subprocess.run")
+    def test_install_with_break_system_packages(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0)
+        with patch.dict(os.environ, {"PIP_BREAK_SYSTEM_PACKAGES": "1"}):
+            _install_python_deps(".venv/bin", "ci")
+        mock_run.assert_called_once_with(
+            [".venv/bin/pip", "install", "-e", ".[ci]", "--break-system-packages"], check=False
+        )
 
     @patch("devx.tools.setup._run")
-    def test_install_custom_extras(self, mock_run: MagicMock) -> None:
-        _install_python_deps(".venv/bin", "ci,lint")
-        mock_run.assert_called_once_with([".venv/bin/pip", "install", "-e", ".[ci,lint]"])
+    @patch("devx.tools.setup.subprocess.run")
+    def test_install_retry_with_ignore_installed(self, mock_subprocess: MagicMock, mock_run: MagicMock) -> None:
+        mock_subprocess.return_value = MagicMock(returncode=1)
+        with patch.dict(os.environ, {"PIP_BREAK_SYSTEM_PACKAGES": "1"}):
+            _install_python_deps(".venv/bin", "ci")
+        mock_run.assert_called_once_with(
+            [".venv/bin/pip", "install", "-e", ".[ci]", "--break-system-packages", "--ignore-installed"]
+        )
+
+    @patch("devx.tools.setup.subprocess.run")
+    def test_install_failure_without_break_system(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=1)
+        with pytest.raises(subprocess.CalledProcessError):
+            _install_python_deps(".venv/bin", "ci")
 
 
 class TestInstallPreCommitHooks:
@@ -60,8 +89,9 @@ class TestInstallPreCommitHooks:
 
 
 class TestInstallAnsibleCollections:
+    @patch("devx.tools.setup.shutil.which", return_value="/usr/local/bin/ansible-galaxy")
     @patch("devx.tools.setup._run")
-    def test_installs_from_requirements(self, mock_run: MagicMock, tmp_path: Path) -> None:
+    def test_installs_from_requirements(self, mock_run: MagicMock, mock_which: MagicMock, tmp_path: Path) -> None:
         req = tmp_path / "ansible" / "requirements.yml"
         req.parent.mkdir(parents=True)
         req.write_text("collections: []")

tests/unit/test_start_docker.py

@@ -0,0 +1,111 @@
+"""Unit tests for devx.molecule.start_docker."""
+
+from unittest.mock import MagicMock, patch
+
+from click.testing import CliRunner
+
+from devx.molecule.start_docker import is_docker_ready, main, start_docker_daemon
+
+
+class TestIsDockerReady:
+    @patch("devx.molecule.start_docker.subprocess.run")
+    def test_ready(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0)
+        assert is_docker_ready() is True
+        mock_run.assert_called_once_with(["docker", "info"], capture_output=True, check=False)
+
+    @patch("devx.molecule.start_docker.subprocess.run")
+    def test_not_ready(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=1)
+        assert is_docker_ready() is False
+
+
+class TestStartDockerDaemon:
+    @patch("devx.molecule.start_docker.time.sleep")
+    @patch("devx.molecule.start_docker.is_docker_ready")
+    @patch("devx.molecule.start_docker.subprocess.Popen")
+    @patch("devx.molecule.start_docker.tempfile.NamedTemporaryFile")
+    def test_starts_successfully(
+        self,
+        mock_ntf: MagicMock,
+        mock_popen: MagicMock,
+        mock_ready: MagicMock,
+        mock_sleep: MagicMock,
+    ) -> None:
+        mock_ntf.return_value = MagicMock()
+        # First loop iteration: dockerd not ready yet. Second: ready.
+        mock_ready.side_effect = [False, True]
+        assert start_docker_daemon(timeout=5) is True
+        mock_popen.assert_called_once()
+        mock_sleep.assert_called_once_with(1)
+
+    @patch("devx.molecule.start_docker.time.sleep")
+    @patch("devx.molecule.start_docker.is_docker_ready", return_value=False)
+    @patch("devx.molecule.start_docker.subprocess.Popen")
+    @patch("devx.molecule.start_docker.tempfile.NamedTemporaryFile")
+    def test_fails_after_timeout(
+        self,
+        mock_ntf: MagicMock,
+        mock_popen: MagicMock,
+        mock_ready: MagicMock,
+        mock_sleep: MagicMock,
+    ) -> None:
+        mock_ntf.return_value = MagicMock()
+        assert start_docker_daemon(timeout=3) is False
+        mock_popen.assert_called_once()
+        assert mock_sleep.call_count == 3
+
+    @patch("devx.molecule.start_docker.time.sleep")
+    @patch("devx.molecule.start_docker.is_docker_ready")
+    @patch("devx.molecule.start_docker.subprocess.Popen")
+    @patch("devx.molecule.start_docker.tempfile.NamedTemporaryFile")
+    def test_ready_on_first_check(
+        self,
+        mock_ntf: MagicMock,
+        mock_popen: MagicMock,
+        mock_ready: MagicMock,
+        mock_sleep: MagicMock,
+    ) -> None:
+        mock_ntf.return_value = MagicMock()
+        mock_ready.return_value = True
+        assert start_docker_daemon(timeout=5) is True
+        mock_popen.assert_called_once()
+        mock_sleep.assert_not_called()
+
+    @patch("devx.molecule.start_docker.time.sleep")
+    @patch("devx.molecule.start_docker.is_docker_ready")
+    @patch("devx.molecule.start_docker.subprocess.Popen")
+    @patch("devx.molecule.start_docker.tempfile.NamedTemporaryFile")
+    def test_custom_timeout(
+        self,
+        mock_ntf: MagicMock,
+        mock_popen: MagicMock,
+        mock_ready: MagicMock,
+        mock_sleep: MagicMock,
+    ) -> None:
+        mock_ntf.return_value = MagicMock()
+        # 9 iterations not ready, 10th ready.
+        mock_ready.side_effect = [False] * 9 + [True]
+        assert start_docker_daemon(timeout=10) is True
+        assert mock_sleep.call_count == 9
+
+
+class TestMain:
+    @patch("devx.molecule.start_docker.start_docker_daemon", return_value=True)
+    def test_success(self, mock_start: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 0
+
+    @patch("devx.molecule.start_docker.start_docker_daemon", return_value=False)
+    def test_failure(self, mock_start: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, [])
+        assert result.exit_code == 1
+
+    @patch("devx.molecule.start_docker.start_docker_daemon", return_value=True)
+    def test_custom_timeout_flag(self, mock_start: MagicMock) -> None:
+        runner = CliRunner()
+        result = runner.invoke(main, ["--timeout", "60"])
+        assert result.exit_code == 0
+        mock_start.assert_called_once_with(60)