behave-pool 1.0.0__py3-none-any.whl

behave_pool/__init__.py

@@ -0,0 +1,21 @@
+"""behave-pool: parallel test execution for Behave BDD via native ITestRunner.
+
+Public API:
+
+    from behave_pool import ParallelRunner
+
+    # Register in behave.ini:
+    # [behave.runners]
+    # parallel = behave_pool:ParallelRunner
+
+    # Then run:
+    # behave --runner=parallel --parallel 4 --parallel-scheme feature features/
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from behave_pool.runner import ParallelRunner
+
+__all__ = ["ParallelRunner", "__version__"]

behave_pool/config.py

@@ -0,0 +1,131 @@
+"""Parallel configuration options for behave-pool."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from behave.configuration import Configuration
+
+
+def _register_parallel_options() -> None:
+    """Register --parallel-scheme and --parallel-balance in behave's OPTIONS list (once)."""
+    from behave.configuration import OPTIONS
+
+    existing: set[str] = set()
+    for fixed, _ in OPTIONS:
+        if fixed:
+            existing.add(fixed[0])
+
+    if "--parallel-scheme" not in existing:
+        OPTIONS.append(
+            (
+                ("--parallel-scheme",),
+                {
+                    "dest": "parallel_scheme",
+                    "default": "feature",
+                    "help": "Parallelization scheme: feature (default: %(default)s).",
+                },
+            ),
+        )
+
+    if "--parallel-balance" not in existing:
+        OPTIONS.append(
+            (
+                ("--parallel-balance",),
+                {
+                    "dest": "parallel_balance",
+                    "default": "lpt",
+                    "choices": ["lpt", "fifo"],
+                    "help": (
+                        "Work unit ordering: lpt (longest first) or fifo (default: %(default)s)."
+                    ),
+                },
+            ),
+        )
+
+    if "--parallel-timing-file" not in existing:
+        OPTIONS.append(
+            (
+                ("--parallel-timing-file",),
+                {
+                    "dest": "parallel_timing_file",
+                    "default": ".behave-pool-timing.json",
+                    "help": "Path to timing file for LPT balancing (default: %(default)s).",
+                },
+            ),
+        )
+
+
+_register_parallel_options()
+
+
+@dataclass(frozen=True)
+class ConfigSnapshot:
+    """Picklable snapshot of essential Configuration fields for worker processes.
+
+    The full behave Configuration contains non-picklable objects (file
+    handles, reporters).  This snapshot captures only the fields needed
+    by WorkerRunner to execute features.
+    """
+
+    base_dir: str
+    steps_dir: str
+    environment_file: str
+    lang: str | None
+    stop: bool
+    paths: list[str] = field(default_factory=list)
+    parallel: int = 1
+    parallel_scheme: str = "feature"
+    parallel_balance: str = "lpt"
+    parallel_timing_file: str = ".behave-pool-timing.json"
+    dry_run: bool = False
+    use_nested_step_modules: bool = False
+
+
+def snapshot_config(config: Configuration) -> ConfigSnapshot:
+    """Create a picklable snapshot from a Configuration instance."""
+    return ConfigSnapshot(
+        base_dir=str(getattr(config, "base_dir", None) or "features"),
+        steps_dir=str(getattr(config, "steps_dir", None) or "steps"),
+        environment_file=str(getattr(config, "environment_file", None) or "environment.py"),
+        lang=config.lang,
+        stop=config.stop,
+        paths=[str(p) for p in config.paths] if config.paths else [],
+        parallel=getattr(config, "parallel", None) or getattr(config, "jobs", None) or 1,
+        parallel_scheme=getattr(config, "parallel_scheme", "feature"),
+        parallel_balance=getattr(config, "parallel_balance", "lpt"),
+        parallel_timing_file=str(
+            getattr(config, "parallel_timing_file", None) or ".behave-pool-timing.json"
+        ),
+        dry_run=config.dry_run,
+        use_nested_step_modules=getattr(config, "use_nested_step_modules", False),
+    )
+
+
+def add_parallel_options(config: Configuration) -> None:
+    """Add parallel-related attributes to a Configuration instance.
+
+    Maps behave's ``config.jobs`` (from ``--parallel``/``--jobs``) to
+    ``config.parallel`` and ensures ``config.parallel_scheme`` exists.
+
+    Args:
+        config: Behave Configuration instance to augment.
+    """
+    jobs = getattr(config, "jobs", 1)
+    if jobs is None:
+        jobs = 1
+    config.parallel = jobs
+
+    if not hasattr(config, "parallel_scheme") or config.parallel_scheme is None:
+        config.parallel_scheme = "feature"
+
+    if not hasattr(config, "parallel_balance") or config.parallel_balance is None:
+        config.parallel_balance = "lpt"
+
+    if not hasattr(config, "parallel_timing_file") or config.parallel_timing_file is None:
+        config.parallel_timing_file = ".behave-pool-timing.json"
+
+    if not hasattr(config, "use_nested_step_modules"):
+        config.use_nested_step_modules = False

behave_pool/iterator.py

@@ -0,0 +1,81 @@
+"""Strategy pattern for iterating work units from Behave features."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+from behave_pool.config import snapshot_config
+from behave_pool.work_unit import WorkUnit
+
+if TYPE_CHECKING:
+    from behave.configuration import Configuration
+    from behave.model import Feature
+
+
+class WorkUnitIterator(ABC):
+    """Abstract strategy for generating WorkUnits from parsed features."""
+
+    @abstractmethod
+    def iterate(self) -> Iterator[WorkUnit]:
+        """Yield WorkUnit instances one at a time."""
+        ...
+
+    @staticmethod
+    def for_scheme(
+        scheme: str,
+        features: list[Feature],
+        config: Configuration,
+    ) -> WorkUnitIterator:
+        """Factory: return the iterator for the given parallel scheme.
+
+        Args:
+            scheme: "feature" or "scenario".
+            features: Parsed Behave Feature objects.
+            config: Coordinator's Configuration (will be deep-copied per unit).
+
+        Returns:
+            A WorkUnitIterator instance for the requested scheme.
+
+        Raises:
+            ValueError: If scheme is not recognised.
+            NotImplementedError: If scheme is "scenario" (not yet implemented).
+        """
+        if scheme == "feature":
+            return FeatureIterator(features, config)
+        if scheme == "scenario":
+            raise NotImplementedError("ScenarioIterator is not yet implemented")
+        msg = f"Unknown parallel scheme: {scheme!r}. Use 'feature' or 'scenario'."
+        raise ValueError(msg)
+
+
+class FeatureIterator(WorkUnitIterator):
+    """Generate one WorkUnit per feature file.
+
+    Each WorkUnit contains an isolated deep copy of the Configuration
+    so that workers can execute independently without shared mutable state.
+    """
+
+    def __init__(self, features: list[Feature], config: Configuration) -> None:
+        self._features = features
+        self._config = config
+
+    def iterate(self) -> Iterator[WorkUnit]:
+        """Yield one WorkUnit per feature.
+
+        Tags are collected from both the feature and its scenarios.
+        If any scenario has the ``serial`` tag, the work unit is
+        marked serial so it runs in the serial phase.
+        """
+        for feature in self._features:
+            tags = set(str(t) for t in (getattr(feature, "tags", None) or []))
+            for scenario in getattr(feature, "scenarios", None) or []:
+                tags.update(str(t) for t in (getattr(scenario, "tags", None) or []))
+            yield WorkUnit(
+                id=f"feature:{feature.filename}",
+                config=snapshot_config(self._config),
+                feature_path=feature.filename,
+                scenario_line=None,
+                tags=list(tags),
+            )

behave_pool/result.py

@@ -0,0 +1,32 @@
+"""WorkerResult: the outcome of executing a WorkUnit in a worker process."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class WorkerResult:
+    """Result of a worker executing a single WorkUnit.
+
+    Produced by WorkerRunner.run_work_unit() and sent back to the
+    coordinator via the result queue for aggregation.
+
+    Attributes:
+        worker_id: Identifier of the worker process that produced this result.
+        work_unit_id: ID of the WorkUnit that was executed.
+        failed: True if any scenario or step in the work unit failed.
+        duration: Wall-clock execution time in seconds.
+        report_path: Path to the temporary JSON report file, or None if
+            no report was written.
+        undefined_steps: List of undefined step text patterns encountered.
+        error: Error message if the worker process crashed, None otherwise.
+    """
+
+    worker_id: int
+    work_unit_id: str
+    failed: bool
+    duration: float
+    report_path: str | None = None
+    undefined_steps: list[str] = field(default_factory=list)
+    error: str | None = None

behave_pool/runner.py

@@ -0,0 +1,343 @@
+"""ParallelRunner: coordinator that orchestrates parallel feature execution."""
+
+from __future__ import annotations
+
+import logging
+import multiprocessing
+import os
+import queue
+import shutil
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from behave.runner import Runner, make_formatters, parse_features
+
+from behave_pool.config import add_parallel_options, snapshot_config
+from behave_pool.iterator import WorkUnitIterator
+from behave_pool.result import WorkerResult
+from behave_pool.timing import TimingStore
+from behave_pool.worker import WorkerProcess
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from behave.configuration import Configuration
+
+    from behave_pool.work_unit import WorkUnit
+
+logger = logging.getLogger(__name__)
+
+
+class ParallelRunner(Runner):  # type: ignore[misc]
+    """Coordinator that dispatches work units to worker processes.
+
+    When ``config.parallel <= 1`` it falls back to the standard Behave
+    sequential runner.  Otherwise it plans, dispatches, and collects
+    results from N worker processes.
+    """
+
+    def __init__(self, config: Configuration) -> None:
+        super().__init__(config)
+        add_parallel_options(config)
+
+    def run(self) -> bool:
+        """Run the test suite — parallel or sequential depending on config."""
+        with self.path_manager:
+            self.setup_paths()
+            return self.run_with_paths()
+
+    def run_with_paths(self) -> bool:
+        """Run tests with configured paths.
+
+        If ``config.parallel <= 1`` delegates to the standard sequential
+        runner.  Otherwise enters the parallel pipeline.
+        """
+        if self.config.parallel <= 1:
+            return self._run_sequential()
+
+        return self._run_parallel()
+
+    def _run_sequential(self) -> bool:
+        """Standard Behave sequential execution."""
+        from behave.runner import Context
+
+        self.context = Context(self)
+        self.load_hooks()
+        self.load_step_definitions()
+
+        feature_locations = [
+            filename for filename in self.feature_locations() if not self.config.exclude(filename)
+        ]
+        features = parse_features(feature_locations, language=self.config.lang)
+        self.features.extend(features)
+
+        stream_openers = self.config.outputs
+        self.formatters = make_formatters(self.config, stream_openers)
+        failed: bool = self.run_model()
+        return failed
+
+    def _run_parallel(self) -> bool:
+        """Execute the parallel pipeline: plan -> split -> dispatch -> collect."""
+        ctx = multiprocessing.get_context("spawn")
+        task_queue: Any = ctx.JoinableQueue()
+        result_queue: Any = ctx.Queue()
+        stop_event: Any = ctx.Event()
+
+        try:
+            work_units = self._plan()
+            parallel_batch, serial_batch = self._split_by_serial_tag(work_units)
+            dispatched = self._dispatch(
+                task_queue, result_queue, stop_event, parallel_batch, serial_batch
+            )
+            return self._collect(result_queue, dispatched)
+        finally:
+            stop_event.set()
+            task_queue.close()
+            result_queue.close()
+
+    def _plan(self) -> list[WorkUnit]:
+        """Parse features and create work units.
+
+        Returns:
+            List of work units to execute.
+        """
+        from behave.runner import Context
+
+        self.context = Context(self)
+        self.load_hooks()
+
+        feature_locations = [
+            filename for filename in self.feature_locations() if not self.config.exclude(filename)
+        ]
+        features = parse_features(feature_locations, language=self.config.lang)
+        self.features.extend(features)
+
+        iterator = WorkUnitIterator.for_scheme(
+            scheme=self.config.parallel_scheme,
+            features=features,
+            config=self.config,
+        )
+        work_units = list(iterator.iterate())
+        work_units = self._sort_by_duration(work_units)
+
+        return work_units
+
+    def _sort_by_duration(self, units: list[WorkUnit]) -> list[WorkUnit]:
+        """Sort work units by historical duration (LPT) or keep FIFO order.
+
+        When ``config.parallel_balance`` is ``"lpt"``, units are sorted
+        descending by their stored duration in the TimingStore so that
+        the longest jobs start first, improving overall wall-clock time.
+
+        When ``config.parallel_balance`` is ``"fifo"``, the original
+        order is preserved.
+
+        Args:
+            units: Work units to sort.
+
+        Returns:
+            Sorted list of work units.
+        """
+        balance = getattr(self.config, "parallel_balance", "lpt")
+        if balance == "fifo":
+            return units
+
+        timing_file = (
+            getattr(self.config, "parallel_timing_file", None) or ".behave-pool-timing.json"
+        )
+        store = TimingStore(path=Path(timing_file))
+        store.load()
+        return sorted(units, key=lambda u: store.get_duration(u.id), reverse=True)
+
+    @staticmethod
+    def _split_by_serial_tag(
+        units: list[WorkUnit],
+    ) -> tuple[list[WorkUnit], list[WorkUnit]]:
+        """Split work units into parallel and serial batches.
+
+        Args:
+            units: All work units to split.
+
+        Returns:
+            Tuple of (parallel_batch, serial_batch).
+        """
+        parallel_batch = [u for u in units if not u.is_serial]
+        serial_batch = [u for u in units if u.is_serial]
+        return parallel_batch, serial_batch
+
+    def _dispatch(
+        self,
+        task_queue: Any,
+        result_queue: Any,
+        stop_event: Any,
+        parallel_batch: list[WorkUnit],
+        serial_batch: list[WorkUnit],
+    ) -> list[WorkUnit]:
+        """Two-phase dispatch: parallel first, then serial.
+
+        Phase 1: enqueue parallel_batch, launch N workers, wait for completion.
+        Phase 2: enqueue serial_batch one at a time, launch 1 worker, wait.
+
+        Returns:
+            List of work units that were actually enqueued (dispatched).
+        """
+        n_workers = self.config.parallel
+        config_snapshot = snapshot_config(self.config)
+        dispatched: list[WorkUnit] = []
+        ctx = multiprocessing.get_context("spawn")
+
+        # -- Phase 1: parallel batch with N workers.
+        if parallel_batch:
+            for unit in parallel_batch:
+                task_queue.put(unit)
+            for _ in range(n_workers):
+                task_queue.put(None)
+            dispatched.extend(parallel_batch)
+
+            workers: list[WorkerProcess] = []
+            for worker_id in range(n_workers):
+                worker = WorkerProcess(
+                    worker_id=worker_id,
+                    task_queue=task_queue,
+                    result_queue=result_queue,
+                    stop_event=stop_event,
+                    config_snapshot=config_snapshot,
+                    ctx=ctx,
+                )
+                worker.start()
+                workers.append(worker)
+
+            for worker in workers:
+                worker.join(timeout=300)
+                if worker.is_alive():
+                    logger.warning(
+                        "Worker %d did not terminate within 300s; "
+                        "setting stop event and terminating.",
+                        worker.worker_id,
+                    )
+                    stop_event.set()
+                    worker.terminate()
+
+            # Drain any unconsumed items so the queue is empty for Phase 2.
+            while not task_queue.empty():
+                try:
+                    task_queue.get_nowait()
+                    task_queue.task_done()
+                except queue.Empty:
+                    break
+
+        # -- Phase 2: serial batch with 1 worker.
+        if serial_batch and not stop_event.is_set():
+            for unit in serial_batch:
+                task_queue.put(unit)
+            task_queue.put(None)
+            dispatched.extend(serial_batch)
+
+            serial_worker = WorkerProcess(
+                worker_id=0,
+                task_queue=task_queue,
+                result_queue=result_queue,
+                stop_event=stop_event,
+                config_snapshot=config_snapshot,
+                ctx=ctx,
+            )
+            serial_worker.start()
+            serial_worker.join(timeout=300)
+            if serial_worker.is_alive():
+                logger.warning(
+                    "Serial worker did not terminate within 300s; "
+                    "setting stop event and terminating."
+                )
+                stop_event.set()
+                serial_worker.terminate()
+
+            # Drain any unconsumed items.
+            while not task_queue.empty():
+                try:
+                    task_queue.get_nowait()
+                    task_queue.task_done()
+                except queue.Empty:
+                    break
+
+        return dispatched
+
+    def _collect(
+        self,
+        result_queue: Any,
+        work_units: list[WorkUnit],
+        deadline_seconds: float = 30,
+    ) -> bool:
+        """Drain result queue, merge results, and compute exit code.
+
+        Returns:
+            True if any test failed (Behave convention).
+        """
+        expected = len(work_units)
+        results: list[WorkerResult] = []
+        received_ids: set[str] = set()
+
+        # Drain all available results, waiting up to deadline_seconds for late arrivals.
+        deadline = time.monotonic() + deadline_seconds
+        while len(results) < expected and time.monotonic() < deadline:
+            try:
+                result = result_queue.get(timeout=1)
+            except queue.Empty:
+                continue
+            except (EOFError, OSError):
+                break
+            results.append(result)
+            received_ids.add(result.work_unit_id)
+
+        # Detect missing results from crashed or timed-out workers.
+        missing = [u.id for u in work_units if u.id not in received_ids]
+        if missing:
+            logger.warning(
+                "Missing %d result(s) from worker(s): %s",
+                len(missing),
+                ", ".join(missing),
+            )
+
+        any_failed = any(r.failed for r in results)
+
+        # Missing results indicate worker crashes — treat as failures.
+        if missing:
+            any_failed = True
+
+        self._update_timings(results)
+
+        tmp_dir = os.path.join(os.getcwd(), "tmp")
+        if os.path.isdir(tmp_dir):
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+        logger.info(
+            "Parallel run complete: %d work units, %d results, failed=%s",
+            len(work_units),
+            len(results),
+            any_failed,
+        )
+
+        return any_failed
+
+    def _update_timings(self, results: list[WorkerResult]) -> None:
+        """Update the TimingStore with observed durations from results.
+
+        Timing persistence is best-effort: any failure is logged and
+        does not affect the test run outcome.
+
+        Args:
+            results: Worker results containing durations to persist.
+        """
+        timing_file = (
+            getattr(self.config, "parallel_timing_file", None) or ".behave-pool-timing.json"
+        )
+        try:
+            store = TimingStore(path=Path(timing_file))
+            store.load()
+            for result in results:
+                store.update(result.work_unit_id, result.duration)
+            store.save_if_changed()
+        except Exception:
+            logger.warning(
+                "Failed to update timing file %s; timings will not persist.", timing_file
+            )