throngtest 0.0.1__py3-none-any.whl

throngtest/coverage.py

@@ -0,0 +1,157 @@
+"""Coverage agents discovered through a pristan slot."""
+
+import os
+from abc import ABC, abstractmethod
+from importlib import import_module
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, cast
+
+import pytest
+from pristan import slot
+
+from throngtest.coverage_transport import worker_data_file
+
+if TYPE_CHECKING:  # pragma: no cover - this import only exists for static analysis.
+    from coverage import Coverage
+
+
+class CoverageAgent(ABC):
+    """Adapt one coverage provider to the isolate lifecycle."""
+
+    @abstractmethod
+    def active(self, config: pytest.Config) -> bool:
+        ...  # pragma: no cover - abstract signature.
+
+    @abstractmethod
+    def start_worker(self, marker: str, configuration: Dict[str, object], root: Path) -> None:
+        ...  # pragma: no cover - abstract signature.
+
+    def configuration(self, _root: Path) -> Dict[str, object]:
+        """Return JSON-safe settings needed by this agent in an isolate."""
+        return {}
+
+    def pytest_arguments(self) -> List[str]:
+        """Override provider options that must be evaluated by the controller."""
+        return []
+
+    @abstractmethod
+    def stop_worker(self) -> None:
+        ...  # pragma: no cover - abstract signature.
+
+    def data_file(self) -> str:
+        """Return the provider's configured coverage data file in this process."""
+        from coverage import Coverage  # noqa: PLC0415
+        current = Coverage.current()
+        return str(current.config.data_file if current is not None else Coverage().config.data_file)
+
+
+@slot(entrypoint_group='throngtest.coverage')
+def coverage_agents() -> Dict[str, CoverageAgent]:  # type: ignore[empty-body]
+    ...  # pragma: no cover - pristan replaces the slot body.
+
+
+class PythonCoverageAgent(CoverageAgent):
+    """Start coverage.py in a worker created by ``coverage run``."""
+
+    def __init__(self) -> None:
+        self.started: Optional['Coverage'] = None
+        self.config_path: Optional[Path] = None
+
+    def active(self, config: pytest.Config) -> bool:
+        try:
+            from coverage import Coverage  # noqa: PLC0415
+        except ImportError:
+            return False
+        return Coverage.current() is not None and not bool(cast(Optional[List[str]], config.getoption('cov_source', default=None)))
+
+    def configuration(self, root: Path) -> Dict[str, object]:
+        from coverage import Coverage  # noqa: PLC0415
+        current = Coverage.current()
+        assert current is not None
+        filename = current.config.config_file
+        path = Path(filename) if filename else None
+        return {
+            'suffix': path.suffix if path else '',
+            'text': path.read_text() if path and path.is_file() else '',
+            'source': current.config.source,
+            'branch': current.config.branch,
+            'root': str(root),
+        }
+
+    def start_worker(self, marker: str, configuration: Dict[str, object], root: Path) -> None:
+        from coverage import Coverage  # noqa: PLC0415
+        if Coverage.current() is None:
+            os.environ['COVERAGE_FILE'] = worker_data_file(marker)
+            contents = cast(str, configuration.get('text', ''))
+            if contents:
+                suffix = cast(str, configuration.get('suffix', ''))
+                self.config_path = Path('.throngtest-coverage-config-' + marker.rstrip(':') + suffix)
+                self.config_path.write_text(contents)
+            original_source = cast(Optional[List[str]], configuration.get('source'))
+            source = original_source
+            controller_root = cast(str, configuration.get('root', ''))
+            if controller_root and original_source:
+                controller_path = PureWindowsPath(controller_root) if '\\' in controller_root or ':' in controller_root else PurePosixPath(controller_root)
+
+                def map_source(value: str) -> str:
+                    try:
+                        relative = type(controller_path)(value).relative_to(controller_path)
+                    except ValueError:
+                        return value
+                    return str(root.joinpath(*relative.parts))
+
+                source = [map_source(value) for value in original_source]
+            self.started = Coverage(
+                config_file=str(self.config_path) if self.config_path else True,
+                source=source,
+                branch=cast(bool, configuration.get('branch')),
+            )
+            self.started.start()
+
+    def stop_worker(self) -> None:
+        if self.started is not None:
+            self.started.stop()
+            self.started.save()
+        if self.config_path is not None:
+            self.config_path.unlink()
+
+
+class PytestCovAgent(CoverageAgent):
+    """Use pytest-cov's own worker lifecycle and collect its saved data."""
+
+    def __init__(self) -> None:
+        self.worker_file: Optional[str] = None
+
+    def active(self, config: pytest.Config) -> bool:
+        return bool(cast(Optional[List[str]], config.getoption('cov_source', default=None))) and not cast(bool, config.getoption('no_cov', default=False))
+
+    def start_worker(self, marker: str, _configuration: Dict[str, object], _root: Path) -> None:
+        # pytest-cov 6 and earlier starts a subprocess tracer before this
+        # module runs. Stop it before selecting a per-isolate data file.
+        try:
+            cleanup = cast(Callable[[], None], import_module('pytest_cov.embed').cleanup)
+        except (ImportError, AttributeError):
+            pass
+        else:
+            cleanup()
+        self.worker_file = worker_data_file(marker)
+        os.environ['COVERAGE_FILE'] = self.worker_file
+
+    def stop_worker(self) -> None:
+        pass
+
+    def data_file(self) -> str:
+        return self.worker_file or super().data_file()
+
+    def pytest_arguments(self) -> List[str]:
+        return ['--cov-fail-under=0']
+
+
+@coverage_agents.plugin(unique=True)
+def python_coverage() -> CoverageAgent:
+    return PythonCoverageAgent()
+
+
+@coverage_agents.plugin(unique=True)
+def pytest_cov() -> CoverageAgent:
+    return PytestCovAgent()

throngtest/coverage_transport.py

@@ -0,0 +1,93 @@
+"""Move coverage data through isolate command output, without shared storage."""
+
+import base64
+import hashlib
+import json
+import sys
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from tempfile import TemporaryDirectory
+from typing import Dict, List, Set, cast
+from uuid import uuid4
+
+from throngtest.protocol import Request, WorkerError, encode
+
+
+def marker_path(marker: str) -> Path:
+    return Path('.throngtest-coverage-' + hashlib.sha256(marker.encode()).hexdigest())
+
+
+def worker_data_file(marker: str) -> str:
+    return '.coverage.throngtest-' + hashlib.sha256(marker.encode()).hexdigest()
+
+
+def export(value: str) -> None:
+    """Print all new coverage databases after the pytest process has exited."""
+    request = Request.unpack(value)
+    root = Path.cwd().resolve()
+    directory = root / request.directory
+    marker = directory / marker_path(request.marker)
+    since = marker.stat().st_mtime_ns
+    data_files = cast(Dict[str, str], json.loads(marker.read_text()))
+    files: Dict[str, List[str]] = {}
+    for name in request.coverage_agents or []:
+        candidates: Set[Path] = set()
+        data_file = Path(data_files[name])
+        if not data_file.is_absolute():
+            data_file = directory / data_file
+        candidates.update(root.rglob(data_file.name + '*'))
+        candidates.update(data_file.parent.glob(data_file.name + '*'))
+        files[name] = []
+        for path in sorted(candidates):
+            if path.is_file() and path.stat().st_mtime_ns >= since:
+                content = path.read_bytes()
+                if content.startswith(b'SQLite format 3\x00'):
+                    files[name].append(base64.b64encode(content).decode('ascii'))
+    marker.unlink()
+    sys.stdout.write(request.marker + encode({'version': 1, 'root': str(root), 'files': files}) + '\n')
+
+
+def receive(payload: Dict[str, object], targets: Dict[str, str], root: Path) -> None:
+    """Restore and remap coverage databases before the controller reports."""
+    remote = payload.get('root')
+    files = payload.get('files')
+    if not isinstance(remote, str) or not isinstance(files, dict):
+        raise WorkerError('isolate did not return coverage data')
+    from coverage import CoverageData  # noqa: PLC0415
+    from coverage.exceptions import DataError  # noqa: PLC0415
+    remote_path = PureWindowsPath(remote) if '\\' in remote or ':' in remote else PurePosixPath(remote)
+
+    def map_path(filename: str) -> str:
+        path = type(remote_path)(filename)
+        try:
+            relative = path.relative_to(remote_path)
+        except ValueError:
+            return filename
+        return str(root.joinpath(*relative.parts))
+
+    for name, target in targets.items():
+        records = files.get(name)
+        if not isinstance(records, list) or not records:
+            raise WorkerError(f'isolate did not return coverage data for {name}')
+        for item in cast(List[object], records):
+            if not isinstance(item, str):
+                raise WorkerError('isolate returned malformed coverage data')
+            try:
+                content = base64.b64decode(item, validate=True)
+            except ValueError as error:
+                raise WorkerError('isolate returned malformed coverage data') from error
+            if not content.startswith(b'SQLite format 3\x00'):
+                raise WorkerError('isolate returned malformed coverage data')
+            try:
+                with TemporaryDirectory(prefix='throngtest-coverage-') as temporary:
+                    source = Path(temporary) / 'data'
+                    source.write_bytes(content)
+                    source_data = CoverageData(basename=str(source))
+                    try:
+                        source_data.read()
+                        restored = CoverageData(basename=target, suffix=uuid4().hex)
+                        restored.update(source_data, map_path=map_path)
+                        restored.write()
+                    finally:
+                        source_data.erase()
+            except DataError as error:
+                raise WorkerError('isolate returned malformed coverage data') from error

throngtest/distribution.py

@@ -0,0 +1,54 @@
+"""Deterministic partitions, shared by the controller and the workers."""
+
+from difflib import unified_diff
+from hashlib import sha256
+from itertools import islice
+from typing import Dict, List, Sequence
+
+
+def fingerprint(nodeids: Sequence[str]) -> str:
+    # Length prefixes make the encoding unambiguous even for unusual node IDs.
+    digest = sha256()
+    for nodeid in nodeids:
+        value = nodeid.encode('utf-8')
+        digest.update(len(value).to_bytes(8, 'big'))
+        digest.update(value)
+    return digest.hexdigest()
+
+
+def collection_difference(expected: Sequence[str], actual: Sequence[str]) -> str:
+    difference = list(islice(unified_diff(expected, actual, fromfile='controller', tofile='isolate', n=2, lineterm=''), 101))
+    if len(difference) > 100:
+        difference[-1] = '... collection diff truncated after 100 lines'
+    return '\n'.join([
+        'test collection differs between the controller and the isolate',
+        'Possible causes to check:',
+        '  * Test files were added, removed, or excluded from the isolate snapshot;',
+        '    preparation commands may generate or change files.',
+        '  * Parametrization or parameter IDs depend on environment variables, files,',
+        '    external data, random values, or the current time.',
+        '  * Collection order is unstable, for example parameters come from a set.',
+        '  * Test selection differs: check -k, -m, addopts, configuration,',
+        '    and installed plugins or dependencies.',
+        '  * Absolute paths in parameter IDs change when the project is copied',
+        '    to a different directory, even if the tests are otherwise equivalent.',
+        '',
+        f'controller: {len(expected)} selected tests',
+        f'isolate: {len(actual)} selected tests',
+        *difference,
+    ])
+
+
+def partition(nodeids: Sequence[str], workers: int, mode: str) -> List[List[int]]:
+    if workers < 1:
+        raise ValueError('workers must be positive')
+    if mode not in ('tests', 'files'):
+        raise ValueError('distribution must be tests or files')
+    groups: Dict[str, List[int]] = {}
+    for index, nodeid in enumerate(nodeids):
+        key = nodeid.split('::', 1)[0] if mode == 'files' else str(index)
+        groups.setdefault(key, []).append(index)
+    shards: List[List[int]] = [[] for _ in range(min(workers, len(groups)))]
+    for group in sorted(groups.values(), key=len, reverse=True):
+        min(shards, key=len).extend(group)
+    return [sorted(shard) for shard in shards]

throngtest/plugin.py

@@ -0,0 +1,56 @@
+"""Pytest entry point. Distribution is enabled by default with up to four isolates."""
+
+from typing import Dict, Generator, List, Optional, cast
+
+import pytest
+
+from throngtest.protocol import Request
+from throngtest.runner import Runner
+from throngtest.settings import ARGUMENTS, WORKER, read_settings
+from throngtest.xdist import Shard, suspend
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup('throngtest', 'Run test subsets in throng isolates')
+    group.addoption('--isolates', dest='throngtest_workers', metavar='COUNT', default=None,
+                    help='Maximum isolate count; 0 disables distribution (default: 4)')
+    for name, description in (
+        ('backend', 'Throng plugin name (default: temporary_directory)'),
+        ('distribution', 'Partition by tests or files (default: tests)'),
+        ('python', 'Python executable available inside the isolate'),
+        ('exclude', 'JSON list of patterns excluded from the isolate snapshot'),
+        ('preparation', 'JSON list of commands run in each isolate before pytest (default: [])'),
+    ):
+        group.addoption(f'--throngtest-{name}', default=None, help=description)
+    group.addoption('--throngtest-check-fingerprints', action='store_const', const=True, default=None,
+                    dest='throngtest_check_fingerprints', help='Require identical ordered test collections in all isolates (default: disabled)')
+    group.addoption('--throngtest-no-check-fingerprints', action='store_const', const=False, default=None,
+                    dest='throngtest_check_fingerprints', help='Disable collection fingerprint checks, overriding environment and TOML settings')
+
+
+def pytest_load_initial_conftests(early_config: pytest.Config, args: List[str]) -> None:
+    early_config.stash[ARGUMENTS] = list(args)
+
+
+@pytest.hookimpl(wrapper=True, tryfirst=True)  # type: ignore[misc]
+def pytest_cmdline_main(config: pytest.Config) -> Generator[None, Optional[int], Optional[int]]:
+    if not config.stash.get(WORKER, False) and not hasattr(config, 'workerinput') and read_settings(config).workers:
+        suspend(config)
+    return (yield)
+
+
+@pytest.hookimpl(trylast=True)  # type: ignore[misc]  # pluggy's decorator bound includes Any.
+def pytest_configure(config: pytest.Config) -> None:
+    workerinput = cast(Optional[Dict[str, object]], getattr(config, 'workerinput', None)) or {}
+    if 'throngtest' in workerinput:
+        config.stash[WORKER] = True
+        config.pluginmanager.register(Shard(Request.unpack(cast(str, workerinput['throngtest']))), 'throngtest-shard')
+    if config.stash.get(WORKER, False):
+        return
+    settings = read_settings(config)
+    if settings.workers:
+        if cast(bool, config.getoption('usepdb')):
+            raise pytest.UsageError('throngtest cannot be combined with --pdb')
+        if any(cast(object, config.getoption(name, default=False)) for name in ('lf', 'failedfirst', 'newfirst', 'stepwise')):
+            raise pytest.UsageError('throngtest does not support cache-based selection (--lf/--ff/--nf) or --stepwise')
+        config.pluginmanager.register(Runner(settings), 'throngtest-runner')

throngtest/protocol.py

@@ -0,0 +1,60 @@
+"""A versioned, JSON-only protocol carried by throng's command output."""
+
+import base64
+import json
+from dataclasses import dataclass
+from typing import Dict, List, Optional, cast
+
+
+class WorkerError(Exception):
+    """An isolate failed to produce a complete, trustworthy pytest result."""
+
+    def __init__(self, message: str, exitcode: int = 3) -> None:
+        super().__init__(message)
+        self.exitcode = exitcode
+
+
+def encode(data: Dict[str, object]) -> str:
+    return base64.b64encode(json.dumps(data, ensure_ascii=True).encode('ascii')).decode('ascii')
+
+
+def decode(value: str) -> Dict[str, object]:
+    result = cast(object, json.loads(base64.b64decode(value, validate=True)))
+    if not isinstance(result, dict):
+        raise ValueError('expected a JSON object')
+    return cast(Dict[str, object], result)
+
+
+@dataclass
+class Request:
+    arguments: List[str]
+    fingerprint: Optional[str]
+    workers: int
+    distribution: str
+    shard: int
+    marker: str
+    directory: str
+    coverage_agents: Optional[List[str]] = None
+    coverage_targets: Optional[Dict[str, str]] = None
+    coverage_configurations: Optional[Dict[str, Dict[str, object]]] = None
+
+    def pack(self) -> str:
+        return encode(cast(Dict[str, object], vars(self)))
+
+    @classmethod
+    def unpack(cls, value: str) -> 'Request':
+        data = decode(value)
+        return cls(**data)  # type: ignore[arg-type]
+
+
+def read_response(stdout: str, marker: str) -> Dict[str, object]:
+    for line in reversed(stdout.splitlines()):
+        if line.startswith(marker):
+            try:
+                response = decode(line[len(marker):])
+            except ValueError as error:
+                raise WorkerError(f'invalid worker response: {error}') from error
+            if response.get('version') != 1:
+                raise WorkerError('unsupported worker protocol version')
+            return response
+    raise WorkerError('worker terminated without a result')