pytest-hexaqueue 0.6.0__py3-none-any.whl

pytest_hexaqueue/__init__.py

@@ -0,0 +1,74 @@
+"""pytest-hexaqueue - Distributed Test Slicing, Remote Execution, and Multi-CSP Free-Tier Runner Plugin."""
+
+import importlib
+from typing import Any
+
+__all__ = [
+    "adapters",
+    "domain",
+    "FileContiguousTestSlicer",
+    "HexaqueueTestDispatchClient",
+    "HexaqueueTestDispatchPort",
+    "infra",
+    "InMemoryTestDispatchClient",
+    "ports",
+    "RoundRobinTestSlicer",
+    "SliceOutcomeReport",
+    "TestItemInfo",
+    "TestOutcomeItem",
+    "TestRunSession",
+    "TestSlicerPort",
+    "TestSliceSpec",
+    "WorkspaceDeltaBundle",
+]
+
+_EXPORTS: dict[str, tuple[str, str]] = {
+    "FileContiguousTestSlicer": (
+        "pytest_hexaqueue.adapters.slicer",
+        "FileContiguousTestSlicer",
+    ),
+    "HexaqueueTestDispatchClient": (
+        "pytest_hexaqueue.adapters.client",
+        "HexaqueueTestDispatchClient",
+    ),
+    "HexaqueueTestDispatchPort": (
+        "pytest_hexaqueue.ports.client",
+        "HexaqueueTestDispatchPort",
+    ),
+    "InMemoryTestDispatchClient": (
+        "pytest_hexaqueue.adapters.client",
+        "InMemoryTestDispatchClient",
+    ),
+    "RoundRobinTestSlicer": (
+        "pytest_hexaqueue.adapters.slicer",
+        "RoundRobinTestSlicer",
+    ),
+    "SliceOutcomeReport": ("pytest_hexaqueue.domain.outcome", "SliceOutcomeReport"),
+    "TestItemInfo": ("pytest_hexaqueue.domain.slice", "TestItemInfo"),
+    "TestOutcomeItem": ("pytest_hexaqueue.domain.outcome", "TestOutcomeItem"),
+    "TestRunSession": ("pytest_hexaqueue.domain.slice", "TestRunSession"),
+    "TestSlicerPort": ("pytest_hexaqueue.ports.slicer", "TestSlicerPort"),
+    "TestSliceSpec": ("pytest_hexaqueue.domain.slice", "TestSliceSpec"),
+    "WorkspaceDeltaBundle": ("pytest_hexaqueue.domain.delta", "WorkspaceDeltaBundle"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily load symbols upon attribute access."""
+    if name in _EXPORTS:
+        mod_name, attr_name = _EXPORTS[name]
+        mod = importlib.import_module(mod_name)
+        val = getattr(mod, attr_name)
+        globals()[name] = val
+        return val
+    if name in ("adapters", "domain", "infra", "ports"):
+        mod = importlib.import_module(f"pytest_hexaqueue.{name}")
+        globals()[name] = mod
+        return mod
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+def __dir__() -> list[str]:
+    """Return public export list including lazy symbols."""
+    return sorted(set(list(globals().keys()) + __all__))

pytest_hexaqueue/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Adapter implementations for pytest-hexaqueue."""
+
+from pytest_hexaqueue.adapters.client import (
+    HexaqueueTestDispatchClient,
+    InMemoryTestDispatchClient,
+)
+from pytest_hexaqueue.adapters.slicer import (
+    FileContiguousTestSlicer,
+    RoundRobinTestSlicer,
+)
+
+__all__ = [
+    "FileContiguousTestSlicer",
+    "HexaqueueTestDispatchClient",
+    "InMemoryTestDispatchClient",
+    "RoundRobinTestSlicer",
+]

pytest_hexaqueue/adapters/client.py

@@ -0,0 +1,188 @@
+"""Test dispatch client adapters connecting pytest to Hexaqueue clusters.
+
+Notes/Architectural Intent:
+    Provides HTTP/REST communication with hexaqueue-server for remote execution
+    alongside InMemoryTestDispatchClient for hermetic testing, local fallbacks,
+    and property test verification.
+"""
+
+from typing import Any
+
+import httpx
+
+from pytest_hexaqueue.domain.delta import WorkspaceDeltaBundle
+from pytest_hexaqueue.domain.outcome import (
+    SliceOutcomeReport,
+    TestOutcomeItem,
+)
+from pytest_hexaqueue.domain.slice import TestRunSession
+from pytest_hexaqueue.ports.client import HexaqueueTestDispatchPort
+
+
+class HexaqueueTestDispatchClient(HexaqueueTestDispatchPort):
+    """Production client dispatching test runs to Hexaqueue cluster controllers.
+
+    Args:
+        server_url: Base URL of the Hexaqueue controller.
+        timeout_seconds: HTTP request timeout limit.
+        api_token: Optional Bearer authentication token for secure control-plane communication.
+
+    Notes/Architectural Intent:
+        Enforces separation of control-plane authentication from compute-plane CSP credentials.
+        The client passes an optional Bearer token to authenticate with the Hexaqueue cluster
+        controller without requiring any CSP admin keys or cloud SDK access on the test runner.
+    """
+
+    def __init__(
+        self,
+        server_url: str = "http://127.0.0.1:8000",
+        timeout_seconds: float = 30.0,
+        api_token: str | None = None,
+    ) -> None:
+        self.server_url = server_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self.api_token = api_token
+
+    def _headers(self) -> dict[str, str]:
+        """Build request headers including Bearer authorization when configured."""
+        headers: dict[str, str] = {}
+        if self.api_token:
+            headers["Authorization"] = f"Bearer {self.api_token}"
+        return headers
+
+    async def health_check(self) -> bool:
+        """Query cluster controller health status endpoint."""
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.timeout_seconds, headers=self._headers()
+            ) as client:
+                resp = await client.get(f"{self.server_url}/health")
+                return resp.status_code == 200
+        except (httpx.HTTPError, OSError):
+            return False
+
+    async def dispatch_run(
+        self,
+        session: TestRunSession,
+        bundle: WorkspaceDeltaBundle | None = None,
+    ) -> list[SliceOutcomeReport]:
+        """Dispatch test slices to controller via HTTP API."""
+        payload: dict[str, Any] = {
+            "session_id": session.session_id,
+            "pool": session.pool,
+            "free_tier": session.free_tier,
+            "container": session.container,
+            "container_image": session.container_image,
+            "coverage_sources": session.coverage_sources,
+            "slices": [s.model_dump() for s in session.slices],
+            "bundle": bundle.model_dump() if bundle else None,
+        }
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=self.timeout_seconds, headers=self._headers()
+            ) as client:
+                resp = await client.post(
+                    f"{self.server_url}/api/v1/test/runs",
+                    json=payload,
+                )
+                if resp.status_code != 200:
+                    msg = f"Failed to submit test run: HTTP {resp.status_code} - {resp.text}"
+                    raise ConnectionError(msg)
+
+                raw_reports = resp.json().get("reports", [])
+                return [SliceOutcomeReport.model_validate(r) for r in raw_reports]
+        except (httpx.HTTPError, OSError) as exc:
+            msg = f"Hexaqueue cluster at '{self.server_url}' is unreachable: {exc}"
+            raise ConnectionError(msg) from exc
+
+
+class InMemoryTestDispatchClient(HexaqueueTestDispatchPort):
+    """In-memory simulation and test oracle for hermetic pytest execution.
+
+    Notes/Architectural Intent:
+        Enables offline developer workflows, dual-oracle state testing, and local fallback
+        by simulating multi-worker distributed slice execution in-process.
+    """
+
+    def __init__(
+        self,
+        default_provider: str = "LOCAL",
+        is_free_tier: bool = False,
+        fail_nodeids: set[str] | None = None,
+        is_healthy: bool = True,
+    ) -> None:
+        self.default_provider = default_provider
+        self.is_free_tier = is_free_tier
+        self.fail_nodeids = fail_nodeids or set()
+        self.is_healthy = is_healthy
+        self.dispatched_sessions: list[TestRunSession] = []
+
+    async def health_check(self) -> bool:
+        """Return configured simulated health status."""
+        return self.is_healthy
+
+    async def dispatch_run(
+        self,
+        session: TestRunSession,
+        bundle: WorkspaceDeltaBundle | None = None,
+    ) -> list[SliceOutcomeReport]:
+        """Simulate distributed execution of each slice across mock providers."""
+        if not self.is_healthy:
+            msg = "Simulated cluster is unhealthy or unreachable"
+            raise ConnectionError(msg)
+
+        self.dispatched_sessions.append(session)
+        reports: list[SliceOutcomeReport] = []
+
+        # Simulated CSP pool cycle for multi-cloud demonstration
+        providers = ["OCI", "GCP", "AWS", "AZURE", "LOCAL"]
+
+        for slice_spec in session.slices:
+            assigned_provider = (
+                providers[slice_spec.slice_index % len(providers)]
+                if session.free_tier
+                else self.default_provider
+            )
+
+            outcomes: list[TestOutcomeItem] = []
+            for nodeid in slice_spec.test_nodeids:
+                if nodeid in self.fail_nodeids:
+                    outcomes.append(
+                        TestOutcomeItem(
+                            nodeid=nodeid,
+                            outcome="failed",
+                            duration_seconds=0.05,
+                            longrepr=f"AssertionError: Simulated test failure for {nodeid}",
+                            stderr="Captured error log",
+                        )
+                    )
+                else:
+                    outcomes.append(
+                        TestOutcomeItem(
+                            nodeid=nodeid,
+                            outcome="passed",
+                            duration_seconds=0.02,
+                            stdout="Captured stdout trace",
+                        )
+                    )
+
+            reports.append(
+                SliceOutcomeReport(
+                    slice_id=slice_spec.slice_id,
+                    slice_index=slice_spec.slice_index,
+                    worker_id=f"worker-{assigned_provider.lower()}-{slice_spec.slice_index}",
+                    provider=assigned_provider,
+                    is_free_tier=session.free_tier,
+                    outcomes=outcomes,
+                    duration_seconds=max(0.1, len(slice_spec.test_nodeids) * 0.02),
+                )
+            )
+
+        return reports
+
+
+__all__ = [
+    "HexaqueueTestDispatchClient",
+    "InMemoryTestDispatchClient",
+]

pytest_hexaqueue/adapters/slicer.py

@@ -0,0 +1,127 @@
+"""Concrete test slicing adapters for distributing pytest items across execution slices.
+
+Notes/Architectural Intent:
+    Provides deterministic test partitioning algorithms: RoundRobinTestSlicer for
+    uniform distribution and FileContiguousTestSlicer to preserve module fixture
+    and setup locality.
+"""
+
+from collections import defaultdict
+
+from pytest_hexaqueue.domain.slice import TestItemInfo, TestSliceSpec
+from pytest_hexaqueue.ports.slicer import TestSlicerPort
+
+
+class RoundRobinTestSlicer(TestSlicerPort):
+    """Partitions test items evenly across slices using round-robin distribution.
+
+    Notes/Architectural Intent:
+        Guarantees that test counts per slice differ by at most 1, achieving
+        near-optimal load balance for uniform duration test suites.
+    """
+
+    __test__ = False
+
+    def slice_items(
+        self, items: list[TestItemInfo], num_slices: int
+    ) -> list[TestSliceSpec]:
+        """Distribute test items cyclically across slices.
+
+        Args:
+            items: List of collected TestItemInfo instances.
+            num_slices: Number of slices to generate.
+
+        Returns:
+            List of partitioned TestSliceSpec instances.
+
+        Raises:
+            ValueError: If num_slices is less than 1.
+        """
+        if num_slices < 1:
+            msg = f"num_slices must be >= 1, got {num_slices}"
+            raise ValueError(msg)
+
+        nodeid_buckets: list[list[str]] = [[] for _ in range(num_slices)]
+        duration_buckets: list[float] = [0.0 for _ in range(num_slices)]
+
+        for i, item in enumerate(items):
+            bucket_idx = i % num_slices
+            nodeid_buckets[bucket_idx].append(item.nodeid)
+            duration_buckets[bucket_idx] += item.estimated_duration
+
+        return [
+            TestSliceSpec(
+                slice_id=f"slice-{idx}",
+                slice_index=idx,
+                test_nodeids=nodeid_buckets[idx],
+                total_estimated_duration=round(duration_buckets[idx], 2),
+                total_slices=num_slices,
+            )
+            for idx in range(num_slices)
+        ]
+
+
+class FileContiguousTestSlicer(TestSlicerPort):
+    """Partitions test items grouping by test module to preserve fixture locality.
+
+    Notes/Architectural Intent:
+        Groups all test functions from the same test file into the same slice
+        whenever possible, avoiding repeated module imports and costly module-scoped
+        or session-scoped fixture initializations across multiple worker nodes.
+    """
+
+    __test__ = False
+
+    def slice_items(
+        self, items: list[TestItemInfo], num_slices: int
+    ) -> list[TestSliceSpec]:
+        """Group test items by file into balanced slices.
+
+        Args:
+            items: List of collected TestItemInfo instances.
+            num_slices: Number of slices to generate.
+
+        Returns:
+            List of partitioned TestSliceSpec instances.
+
+        Raises:
+            ValueError: If num_slices is less than 1.
+        """
+        if num_slices < 1:
+            msg = f"num_slices must be >= 1, got {num_slices}"
+            raise ValueError(msg)
+
+        # Group items by file path
+        by_file: dict[str, list[TestItemInfo]] = defaultdict(list)
+        for item in items:
+            by_file[item.file_path].append(item)
+
+        nodeid_buckets: list[list[str]] = [[] for _ in range(num_slices)]
+        duration_buckets: list[float] = [0.0 for _ in range(num_slices)]
+
+        # Greedy bin-packing of file groups by count/duration
+        for _file_path, file_items in sorted(
+            by_file.items(), key=lambda x: len(x[1]), reverse=True
+        ):
+            # Select bucket with minimal assigned duration
+            min_idx = duration_buckets.index(min(duration_buckets))
+            for item in file_items:
+                nodeid_buckets[min_idx].append(item.nodeid)
+                duration_buckets[min_idx] += item.estimated_duration
+
+        return [
+            TestSliceSpec(
+                slice_id=f"slice-{idx}",
+                slice_index=idx,
+                test_nodeids=nodeid_buckets[idx],
+                total_estimated_duration=round(duration_buckets[idx], 2),
+                total_slices=num_slices,
+            )
+            for idx in range(num_slices)
+        ]
+
+
+__all__ = [
+    "FileContiguousTestSlicer",
+    "RoundRobinTestSlicer",
+]

pytest_hexaqueue/domain/__init__.py

@@ -0,0 +1,21 @@
+"""Domain models and algorithms for pytest-hexaqueue distributed testing."""
+
+from pytest_hexaqueue.domain.delta import WorkspaceDeltaBundle
+from pytest_hexaqueue.domain.outcome import (
+    SliceOutcomeReport,
+    TestOutcomeItem,
+)
+from pytest_hexaqueue.domain.slice import (
+    TestItemInfo,
+    TestRunSession,
+    TestSliceSpec,
+)
+
+__all__ = [
+    "SliceOutcomeReport",
+    "TestItemInfo",
+    "TestOutcomeItem",
+    "TestRunSession",
+    "TestSliceSpec",
+    "WorkspaceDeltaBundle",
+]

pytest_hexaqueue/domain/delta.py

@@ -0,0 +1,38 @@
+"""Domain models for workspace delta snapshotting and content-addressed test code synchronization.
+
+Notes/Architectural Intent:
+    Captures file manifests and cryptographic SHA-256 hashes of test source code,
+    enabling incremental delta synchronization to remote cluster workers via
+    Hexaqueue Collateral CAS storage without syncing unmodified files.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WorkspaceDeltaBundle(BaseModel):
+    """Manifest of workspace files and cryptographic SHA-256 content digests.
+
+    Args:
+        bundle_id: Content-addressed identifier (hexadecimal SHA-256).
+        git_commit: Optional base Git commit SHA.
+        file_hashes: Mapping of relative file paths to their SHA-256 checksums.
+        total_files: Total count of files included in the delta bundle.
+        total_bytes: Total size of all files in bytes.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    bundle_id: str = Field(description="Content-addressed bundle SHA-256 digest")
+    file_hashes: dict[str, str] = Field(
+        default_factory=dict, description="Relative file paths to SHA-256 digests"
+    )
+    git_commit: str | None = Field(
+        default=None, description="Current Git head commit hash"
+    )
+    total_bytes: int = Field(ge=0, description="Total size in bytes")
+    total_files: int = Field(ge=0, description="Total files count")
+
+
+__all__ = [
+    "WorkspaceDeltaBundle",
+]

pytest_hexaqueue/domain/outcome.py

@@ -0,0 +1,101 @@
+"""Domain models for distributed test execution outcomes, reports, and coverage.
+
+Notes/Architectural Intent:
+    Encapsulates granular test outcomes, terminal slice reports, and execution
+    telemetry streamed back from remote cluster workers or local fallbacks.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TestOutcomeItem(BaseModel):
+    """Execution outcome of a single test item.
+
+    Args:
+        nodeid: Pytest test node identifier.
+        outcome: Terminal verdict ('passed', 'failed', 'skipped', 'xfail', 'xpass').
+        duration_seconds: Test execution duration in seconds.
+        longrepr: Optional formatted traceback or skip/failure message.
+        stdout: Standard output captured during test execution.
+        stderr: Standard error captured during test execution.
+    """
+
+    __test__ = False
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    duration_seconds: float = Field(
+        default=0.0, ge=0.0, description="Duration in seconds"
+    )
+    longrepr: str | None = Field(
+        default=None, description="Traceback or explanation message"
+    )
+    nodeid: str = Field(description="Pytest node ID")
+    outcome: str = Field(description="Outcome verdict")
+    stderr: str | None = Field(default=None, description="Captured stderr")
+    stdout: str | None = Field(default=None, description="Captured stdout")
+
+
+class SliceOutcomeReport(BaseModel):
+    """Aggregate execution report for a completed test slice.
+
+    Args:
+        slice_id: Slice identifier.
+        slice_index: Zero-based slice index.
+        worker_id: Worker instance identifier hosting the execution.
+        provider: Hosting Cloud Service Provider or platform name.
+        is_free_tier: Whether the slice executed under Free-Tier Safety Mode.
+        outcomes: Detailed per-test outcome records.
+        duration_seconds: Total walltime execution duration in seconds.
+        coverage_data: Optional serialized coverage data mapping.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    coverage_data: dict[str, Any] | None = Field(
+        default=None, description="Serialized coverage line mappings"
+    )
+    duration_seconds: float = Field(
+        default=0.0, ge=0.0, description="Slice walltime in seconds"
+    )
+    is_free_tier: bool = Field(
+        default=False, description="Executed under zero-cost Free-Tier"
+    )
+    outcomes: list[TestOutcomeItem] = Field(
+        default_factory=list, description="Per-test outcome records"
+    )
+    provider: str | None = Field(
+        default=None, description="Host cloud service provider or pool"
+    )
+    slice_id: str = Field(description="Slice identifier")
+    slice_index: int = Field(ge=0, description="Slice index")
+    worker_id: str | None = Field(
+        default=None, description="Executing worker identifier"
+    )
+
+    @property
+    def passed_count(self) -> int:
+        """Count of passed tests."""
+        return sum(1 for o in self.outcomes if o.outcome == "passed")
+
+    @property
+    def failed_count(self) -> int:
+        """Count of failed tests."""
+        return sum(1 for o in self.outcomes if o.outcome == "failed")
+
+    @property
+    def skipped_count(self) -> int:
+        """Count of skipped tests."""
+        return sum(1 for o in self.outcomes if o.outcome == "skipped")
+
+    @property
+    def is_success(self) -> bool:
+        """Check if all tests passed or were skipped."""
+        return self.failed_count == 0
+
+
+__all__ = [
+    "SliceOutcomeReport",
+    "TestOutcomeItem",
+]

pytest_hexaqueue/domain/slice.py

@@ -0,0 +1,109 @@
+"""Domain models for distributed test item representation and slicing specifications.
+
+Notes/Architectural Intent:
+    Captures individual collected test items, partitioned execution slices,
+    and distributed test session metadata without external framework dependencies.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TestItemInfo(BaseModel):
+    """Metadata describing a single collected pytest item.
+
+    Args:
+        nodeid: Pytest node identifier (e.g., 'tests/unit/test_app.py::test_init').
+        file_path: Relative filesystem path to the test module.
+        line_number: Optional line number where the test is defined.
+        markers: List of pytest marker tags.
+        estimated_duration: Estimated execution time in seconds.
+    """
+
+    __test__ = False
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    estimated_duration: float = Field(
+        default=1.0, ge=0.0, description="Estimated duration in seconds"
+    )
+    file_path: str = Field(description="Relative path to test module")
+    line_number: int | None = Field(
+        default=None, description="Test definition line number"
+    )
+    markers: list[str] = Field(default_factory=list, description="Pytest marker tags")
+    nodeid: str = Field(description="Unique pytest test node ID")
+
+
+class TestSliceSpec(BaseModel):
+    """Specification of an execution partition assigned to a cluster worker.
+
+    Args:
+        slice_id: Unique identifier for the slice (e.g., 'slice-0').
+        slice_index: Zero-based index of this slice.
+        total_slices: Total count of slices in the partitioned run.
+        test_nodeids: Ordered list of test nodeids to execute in this slice.
+        total_estimated_duration: Sum of estimated test durations in seconds.
+    """
+
+    __test__ = False
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    slice_id: str = Field(description="Slice identifier")
+    slice_index: int = Field(ge=0, description="Slice zero-based index")
+    test_nodeids: list[str] = Field(
+        default_factory=list, description="Assigned test node IDs"
+    )
+    total_estimated_duration: float = Field(
+        default=0.0, ge=0.0, description="Summed estimated duration"
+    )
+    total_slices: int = Field(ge=1, description="Total number of slices")
+
+
+class TestRunSession(BaseModel):
+    """State and topology for a distributed pytest execution run.
+
+    Args:
+        session_id: Unique session identifier.
+        total_items: Total count of collected tests across the suite.
+        total_slices: Count of parallel slices generated.
+        slices: Sequence of partitioned TestSliceSpec instances.
+        server_url: Target Hexaqueue cluster controller API URL.
+        pool: Target compute pool for runner placement.
+        free_tier: Whether execution is governed under zero-cost Free-Tier Safety Mode.
+        container: Whether to execute slices inside isolated OCI container sandboxes.
+        container_image: Optional container image tag for worker runtime.
+        coverage_sources: Sequence of source packages or paths for coverage collection.
+    """
+
+    __test__ = False
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    container: bool = Field(
+        default=False, description="Execute slices inside container worker runtime"
+    )
+    container_image: str | None = Field(
+        default=None, description="Optional container image for worker runtime"
+    )
+    coverage_sources: list[str] = Field(
+        default_factory=list,
+        description="Target packages or paths for coverage collection",
+    )
+    free_tier: bool = Field(
+        default=False, description="Enforce zero-cost Free-Tier limits"
+    )
+    pool: str = Field(default="default", description="Target instance pool")
+    server_url: str = Field(
+        default="http://127.0.0.1:8000", description="Hexaqueue controller URL"
+    )
+    session_id: str = Field(description="Unique test session UUID")
+    slices: list[TestSliceSpec] = Field(
+        default_factory=list, description="Partitioned test slices"
+    )
+    total_items: int = Field(ge=0, description="Total collected tests")
+    total_slices: int = Field(ge=1, description="Number of slices")
+
+
+__all__ = [
+    "TestItemInfo",
+    "TestRunSession",
+    "TestSliceSpec",
+]