pyprodtest 0.1.0__py3-none-any.whl

_pyprodtest/config.py

@@ -0,0 +1,163 @@
+"""Load and validate project configuration from pyprodtest.yaml."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import pytest
+import yaml
+
+DEFAULT_UI_NAME = "Production test execution"
+
+
+@dataclass(frozen=True)
+class UiConfig:
+    """Configuration for the live operator UI."""
+
+    enabled: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8765
+
+
+@dataclass(frozen=True)
+class ReportsConfig:
+    """Configuration shared by the final report observers."""
+
+    output: str = "pyprodtest-report"
+    html: bool = True
+    json: bool = True
+    csv: bool = True
+    pdf: bool = True
+
+
+@dataclass(frozen=True)
+class PyProdTestConfig:
+    """Validated settings for one PyProdTest session."""
+
+    name: str = DEFAULT_UI_NAME
+    tests: list[str] | None = None
+    ui: UiConfig = field(default_factory=UiConfig)
+    reports: ReportsConfig = field(default_factory=ReportsConfig)
+
+
+def load_config(rootpath: Path) -> PyProdTestConfig:
+    """Load pyprodtest.yaml from the pytest project root."""
+    config_path = rootpath / "pyprodtest.yaml"
+    if not config_path.exists():
+        return PyProdTestConfig()
+
+    try:
+        document = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as error:
+        raise pytest.UsageError(
+            f"Invalid PyProdTest configuration {config_path}: {error}"
+        ) from error
+    if not isinstance(document, dict):
+        raise pytest.UsageError(
+            f"PyProdTest configuration {config_path} must contain a YAML mapping"
+        )
+
+    name = _non_empty_string(document.get("name", DEFAULT_UI_NAME), "name")
+    tests = _load_tests(document.get("tests"))
+    ui = _mapping(document.get("ui", {}), "ui")
+    reports = _mapping(document.get("reports", {}), "reports")
+    return PyProdTestConfig(
+        name=name,
+        tests=tests,
+        ui=UiConfig(
+            enabled=_boolean(ui.get("enabled", True), "ui.enabled"),
+            host=_non_empty_string(ui.get("host", "127.0.0.1"), "ui.host"),
+            port=_port(ui.get("port", 8765)),
+        ),
+        reports=ReportsConfig(
+            output=_non_empty_string(
+                reports.get("output", "pyprodtest-report"), "reports.output"
+            ),
+            html=_boolean(reports.get("html", True), "reports.html"),
+            json=_boolean(reports.get("json", True), "reports.json"),
+            csv=_boolean(reports.get("csv", True), "reports.csv"),
+            pdf=_boolean(reports.get("pdf", True), "reports.pdf"),
+        ),
+    )
+
+
+def apply_test_plan(
+    config: pytest.Config, items: list[pytest.Item], plan: list[str] | None
+) -> None:
+    """Select and order collected items using the configured test plan."""
+    if plan is None:
+        return
+
+    ranked = [(item, _selection_index(item.nodeid, plan)) for item in items]
+    matched = {plan[index] for _, index in ranked if index < len(plan)}
+    unmatched = [selection for selection in plan if selection not in matched]
+    if unmatched:
+        formatted = "\n  - ".join(unmatched)
+        raise pytest.UsageError(
+            f"PyProdTest plan entries matched no tests:\n  - {formatted}"
+        )
+
+    ranked.sort(key=lambda entry: entry[1])
+    selected = [item for item, index in ranked if index < len(plan)]
+    deselected = [item for item, index in ranked if index == len(plan)]
+    items[:] = selected
+    if deselected:
+        config.hook.pytest_deselected(items=deselected)
+
+
+def _load_tests(value: object) -> list[str] | None:
+    if value is None:
+        return None
+    if not isinstance(value, list) or not all(
+        isinstance(selection, str) and selection for selection in value
+    ):
+        raise pytest.UsageError(
+            "PyProdTest configuration 'tests' must be a list of paths or node IDs"
+        )
+    return [selection.replace("\\", "/") for selection in value]
+
+
+def _mapping(value: object, setting: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be a mapping"
+        )
+    return value
+
+
+def _boolean(value: object, setting: str) -> bool:
+    if not isinstance(value, bool):
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be true or false"
+        )
+    return value
+
+
+def _non_empty_string(value: object, setting: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise pytest.UsageError(
+            f"PyProdTest configuration '{setting}' must be a non-empty string"
+        )
+    return value.strip()
+
+
+def _port(value: object) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= 65535:
+        raise pytest.UsageError(
+            "PyProdTest configuration 'ui.port' must be an integer from 0 to 65535"
+        )
+    return value
+
+
+def _selection_index(nodeid: str, plan: list[str]) -> int:
+    return next(
+        (index for index, selection in enumerate(plan) if _matches(nodeid, selection)),
+        len(plan),
+    )
+
+
+def _matches(nodeid: str, selection: str) -> bool:
+    return (
+        nodeid == selection
+        or nodeid.startswith(f"{selection}::")
+        or nodeid.startswith(f"{selection}[")
+    )

_pyprodtest/decorator.py

@@ -0,0 +1,47 @@
+"""
+Additional decorators for PyProdTest tests.
+These decorators add metadata to test functions and are optional.
+"""
+
+
+def info(name, desc):
+    """
+    Adds name and description metadata to a test function.
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        fn.test_meta["name"] = name
+        fn.test_meta["desc"] = desc
+        return fn
+
+    return wrapper
+
+
+def req(*reqs):
+    """
+    Adds requirement IDs to the metadata.
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        fn.test_meta["requirements"] = list(reqs)
+        return fn
+
+    return wrapper
+
+
+def step(*steps):
+    """
+    Adds step metadata to the metadata
+    """
+
+    def wrapper(fn):
+        fn.test_meta = getattr(fn, "test_meta", {})
+        existing_steps = fn.test_meta.get("steps", [])
+        # Decorators are applied from the bottom upwards, so prepend each
+        # group to retain the order in which stacked decorators are written.
+        fn.test_meta["steps"] = [*steps, *existing_steps]
+        return fn
+
+    return wrapper

_pyprodtest/hooks.py

@@ -0,0 +1,284 @@
+"""Pytest plugin hooks for capturing and forwarding test information."""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+from _pyprodtest.config import PyProdTestConfig, apply_test_plan, load_config
+from _pyprodtest.input_acceptors import ConsoleInputAcceptor, InputAcceptor, TestInput
+from _pyprodtest.observers import (
+    CsvObserver,
+    HtmlObserver,
+    JsonObserver,
+    PdfObserver,
+    TestObserver,
+)
+from _pyprodtest.observers.web_ui import WebUi
+from _pyprodtest.report_settings import ReportSettings
+from _pyprodtest.test_record import CapturedLog, TestRecord
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class PluginState:
+    """State owned by one pytest session."""
+
+    observers: list[TestObserver] = field(default_factory=list)
+    records: dict[str, TestRecord] = field(default_factory=dict)
+    current_test_nodeid: str | None = None
+    log_handler: logging.Handler | None = None
+    input_acceptor: InputAcceptor = field(default_factory=ConsoleInputAcceptor)
+    report_settings: ReportSettings = field(default_factory=ReportSettings)
+    cleanup_callbacks: list[Callable[[], None]] = field(default_factory=list)
+    config: PyProdTestConfig = field(default_factory=PyProdTestConfig)
+
+    def on_tests_collected(self, test_records: list[TestRecord]) -> None:
+        for observer in self.observers:
+            observer.on_tests_collected(test_records)
+
+    def on_test_run(self, test_record: TestRecord) -> None:
+        for observer in self.observers:
+            observer.on_test_run(test_record)
+
+    def on_test_end(self, test_record: TestRecord) -> None:
+        for observer in self.observers:
+            observer.on_test_end(test_record)
+
+
+_state: PluginState | None = None
+
+
+@pytest.fixture(scope="session")
+def report() -> ReportSettings:
+    """Return mutable settings for the final standalone HTML report."""
+    if _state is None:
+        raise RuntimeError("PyProdTest is not configured")
+    return _state.report_settings
+
+
+@pytest.fixture(scope="session")
+def input(request: pytest.FixtureRequest) -> TestInput:
+    """Return input from the acceptor selected by the plugin's run mode."""
+    if _state is None:
+        raise RuntimeError("PyProdTest is not configured")
+
+    def accept(prompt: str, input_type: type[str] | type[bool] = str) -> str | bool:
+        capture_manager = request.config.pluginmanager.get_plugin("capturemanager")
+        if capture_manager is None:
+            return _state.input_acceptor.accept(prompt, input_type)
+
+        # pytest's standard disabled-capture context leaves stdin blocked.
+        # Explicitly include stdin while suspending capture for the prompt.
+        capture_manager.suspend(in_=True)
+        try:
+            return _state.input_acceptor.accept(prompt, input_type)
+        finally:
+            capture_manager.resume()
+
+    return accept
+
+
+class TestLogHandler(logging.Handler):
+    """Attach log records to the currently executing test."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if _state is None or _state.current_test_nodeid is None:
+            return
+
+        test_record = _state.records.get(_state.current_test_nodeid)
+        if test_record is not None:
+            test_record.logs.append(CapturedLog.from_record(record))
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Create isolated plugin state for this pytest session."""
+    global _state
+
+    _enable_live_logging(config)
+
+    project_config = load_config(config.rootpath)
+    report_settings = ReportSettings.from_output_path(
+        _timestamped_report_output(project_config.reports.output)
+    )
+    collect_only = config.getoption("--collect-only")
+    observers, cleanup_callbacks = _create_report_observers(
+        project_config, report_settings, collect_only=collect_only
+    )
+    input_acceptor: InputAcceptor = ConsoleInputAcceptor()
+    if project_config.ui.enabled and not collect_only:
+        web_ui = WebUi(
+            host=project_config.ui.host,
+            port=project_config.ui.port,
+            name=project_config.name,
+        )
+        web_ui.start(open_browser=True)
+        LOGGER.info("PyProdTest web UI: %s", web_ui.url)
+        observers.append(web_ui.observer)
+        input_acceptor = web_ui.input_acceptor
+        cleanup_callbacks.append(web_ui.finish_and_stop)
+
+    root_logger = logging.getLogger()
+    handler = TestLogHandler()
+    root_logger.addHandler(handler)
+    if not root_logger.isEnabledFor(logging.INFO):
+        root_logger.setLevel(logging.INFO)
+
+    _state = PluginState(
+        observers=observers,
+        log_handler=handler,
+        input_acceptor=input_acceptor,
+        report_settings=report_settings,
+        cleanup_callbacks=cleanup_callbacks,
+        config=project_config,
+    )
+    LOGGER.debug("PyProdTest observers configured: %s", observers)
+
+
+def _timestamped_report_output(
+    output: str | Path, timestamp: datetime | None = None
+) -> Path:
+    """Append a filesystem-safe session timestamp to a report basename."""
+    output_path = Path(output)
+    timestamp = timestamp or datetime.now().astimezone()
+    suffix = timestamp.strftime("%Y%m%d-%H%M%S")
+    return output_path.parent / f"{output_path.name}-{suffix}"
+
+
+def _create_report_observers(
+    project_config: PyProdTestConfig,
+    report_settings: ReportSettings,
+    *,
+    collect_only: bool,
+) -> tuple[list[TestObserver], list[Callable[[], None]]]:
+    """Compose only the report observers enabled for this session."""
+    observers: list[TestObserver] = []
+    cleanup_callbacks: list[Callable[[], None]] = []
+
+    if project_config.reports.html:
+        html_observer = HtmlObserver(report_settings)
+        observers.append(html_observer)
+        if not collect_only:
+            cleanup_callbacks.append(html_observer.finalize)
+
+    if project_config.reports.json:
+        json_observer = JsonObserver(report_settings)
+        observers.append(json_observer)
+        if not collect_only:
+            cleanup_callbacks.append(json_observer.finalize)
+
+    if project_config.reports.csv:
+        csv_observer = CsvObserver(report_settings)
+        observers.append(csv_observer)
+        if not collect_only:
+            cleanup_callbacks.append(csv_observer.finalize)
+
+    if project_config.reports.pdf:
+        pdf_observer = PdfObserver(report_settings, project_config.name)
+        observers.append(pdf_observer)
+        if not collect_only:
+            cleanup_callbacks.append(pdf_observer.finalize)
+
+    return observers, cleanup_callbacks
+
+
+def _enable_live_logging(config: pytest.Config) -> None:
+    """Show INFO logs live unless the user configured another CLI level."""
+    if config.getoption("--log-cli-level") is not None:
+        return
+
+    config.option.log_cli_level = config.getini("log_cli_level") or "INFO"
+
+
+def pytest_unconfigure() -> None:
+    """Release state after the pytest session."""
+    global _state
+    if _state is not None and _state.log_handler is not None:
+        root_logger = logging.getLogger()
+        root_logger.removeHandler(_state.log_handler)
+    if _state is not None:
+        for cleanup in _state.cleanup_callbacks:
+            cleanup()
+    _state = None
+
+
+def pytest_report_collectionfinish(items: list[pytest.Item]) -> None:
+    """Build records and notify observers after collection."""
+    if _state is None:
+        return
+
+    for item in items:
+        test_metadata = getattr(getattr(item, "function", None), "test_meta", {})
+        _state.records[item.nodeid] = TestRecord(
+            name=test_metadata.get("name", item.nodeid),
+            description=test_metadata.get("desc", ""),
+            requirements=list(test_metadata.get("requirements", [])),
+            steps=list(test_metadata.get("steps", [])),
+            nodeid=item.nodeid,
+        )
+
+    records = list(_state.records.values())
+    LOGGER.debug("Collected test records: %s", records)
+    _state.on_tests_collected(records)
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    """Apply an optional user-facing test plan to pytest's collected items."""
+    if _state is not None:
+        apply_test_plan(config, items, _state.config.tests)
+
+
+def pytest_runtest_call(item: pytest.Item) -> None:
+    """Notify observers immediately before the test body runs."""
+    if _state is None or (test_record := _state.records.get(item.nodeid)) is None:
+        return
+
+    test_record.outcome = "running"
+    _state.on_test_run(test_record)
+
+
+def pytest_runtest_logstart(nodeid: str, location: tuple[str, int | None, str]) -> None:
+    """Begin attributing log records to a test."""
+    if _state is not None:
+        _state.current_test_nodeid = nodeid
+
+
+def pytest_runtest_logfinish(
+    nodeid: str, location: tuple[str, int | None, str]
+) -> None:
+    """Stop attributing log records after a test finishes."""
+    if _state is not None and _state.current_test_nodeid == nodeid:
+        _state.current_test_nodeid = None
+
+
+def pytest_runtest_logreport(report: pytest.TestReport) -> None:
+    """Capture phase results and notify observers after teardown."""
+    if _state is None or (test_record := _state.records.get(report.nodeid)) is None:
+        return
+
+    _update_test_record(test_record, report)
+
+    if report.when == "teardown":
+        _state.on_test_end(test_record)
+
+
+def _update_test_record(test_record: TestRecord, report: pytest.TestReport) -> None:
+    """Apply one pytest phase report to a domain test record."""
+    test_record.duration += report.duration
+    if report.failed:
+        test_record.outcome = "failed"
+        failure_reason = report.longreprtext or str(report.longrepr)
+        if test_record.failure_reason:
+            test_record.failure_reason += f"\n\n{failure_reason}"
+        else:
+            test_record.failure_reason = failure_reason
+    elif report.when == "call" and test_record.outcome != "failed":
+        test_record.outcome = report.outcome
+    elif report.skipped and test_record.outcome not in {"failed", "passed"}:
+        test_record.outcome = "skipped"

_pyprodtest/input_acceptors.py

@@ -0,0 +1,63 @@
+"""Input acceptors used to obtain operator decisions during tests."""
+
+from abc import ABC, abstractmethod
+from typing import Protocol, overload
+
+
+class TestInput(Protocol):
+    """Callable interface exposed to tests by the ``input`` fixture."""
+
+    @overload
+    def __call__(self, prompt: str, input_type: type[str] = str) -> str: ...
+
+    @overload
+    def __call__(self, prompt: str, input_type: type[bool]) -> bool: ...
+
+    def __call__(
+        self, prompt: str, input_type: type[str] | type[bool] = str
+    ) -> bool | str: ...
+
+
+class InputAcceptor(ABC):
+    """Interface for an operator-facing source of test input."""
+
+    @overload
+    def accept(self, prompt: str, input_type: type[str] = str) -> str: ...
+
+    @overload
+    def accept(self, prompt: str, input_type: type[bool]) -> bool: ...
+
+    @abstractmethod
+    def accept(
+        self, prompt: str, input_type: type[str] | type[bool] = str
+    ) -> bool | str:
+        """Ask an operator for a value of ``input_type``."""
+
+
+class ConsoleInputAcceptor(InputAcceptor):
+    """Obtain operator decisions from the process console."""
+
+    @overload
+    def accept(self, prompt: str, input_type: type[str] = str) -> str: ...
+
+    @overload
+    def accept(self, prompt: str, input_type: type[bool]) -> bool: ...
+
+    def accept(
+        self, prompt: str, input_type: type[str] | type[bool] = str
+    ) -> bool | str:
+        """Read text once, or prompt until receiving an unambiguous yes/no."""
+        print("\n")
+
+        if input_type is str:
+            return input(f"{prompt}: ")
+        if input_type is not bool:
+            raise TypeError("input_type must be bool or str")
+
+        while True:
+            response = input(f"{prompt} [y/n]: ").strip().casefold()
+            if response in {"y", "yes"}:
+                return True
+            if response in {"n", "no"}:
+                return False
+            print("Please answer 'yes' or 'no'.")

_pyprodtest/observers/__init__.py

@@ -0,0 +1,9 @@
+"""Built-in PyProdTest observers."""
+
+from _pyprodtest.observers.csv_report import CsvObserver
+from _pyprodtest.observers.html_report import HtmlObserver
+from _pyprodtest.observers.json_report import JsonObserver
+from _pyprodtest.observers.pdf_report import PdfObserver
+from _pyprodtest.observers.test_observer import TestObserver
+
+__all__ = ["CsvObserver", "HtmlObserver", "JsonObserver", "PdfObserver", "TestObserver"]

_pyprodtest/observers/csv_report/__init__.py

@@ -0,0 +1,5 @@
+"""CSV report observer."""
+
+from _pyprodtest.observers.csv_report.csv_observer import CsvObserver
+
+__all__ = ["CsvObserver"]

_pyprodtest/observers/csv_report/csv_observer.py

@@ -0,0 +1,67 @@
+"""Tabular CSV report observer."""
+
+import csv
+import json
+from collections.abc import Sequence
+from dataclasses import asdict
+
+from _pyprodtest.observers.test_observer import TestObserver
+from _pyprodtest.report_settings import ReportSettings
+from _pyprodtest.test_record import TestRecord
+
+FIELDNAMES = (
+    "name",
+    "description",
+    "nodeid",
+    "outcome",
+    "duration",
+    "requirements",
+    "steps",
+    "failure_reason",
+    "logs",
+)
+
+
+class CsvObserver(TestObserver):
+    """Write one lossless, spreadsheet-friendly row per test."""
+
+    def __init__(self, settings: ReportSettings) -> None:
+        self.settings = settings
+        self._test_records: list[TestRecord] = []
+
+    def on_tests_collected(self, test_records: Sequence[TestRecord]) -> None:
+        self._test_records = list(test_records)
+
+    def on_test_run(self, test_record: TestRecord) -> None:
+        pass
+
+    def on_test_end(self, test_record: TestRecord) -> None:
+        pass
+
+    def finalize(self) -> None:
+        """Write the CSV report when reporting is enabled."""
+        if not self.settings.enabled:
+            return
+        output_path = self.settings.output_path.parent / (
+            f"{self.settings.output_path.name}.csv"
+        )
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with output_path.open("w", encoding="utf-8", newline="") as report_file:
+            writer = csv.DictWriter(report_file, fieldnames=FIELDNAMES)
+            writer.writeheader()
+            for record in self._test_records:
+                writer.writerow(
+                    {
+                        "name": record.name,
+                        "description": record.description,
+                        "nodeid": record.nodeid,
+                        "outcome": record.outcome,
+                        "duration": record.duration,
+                        "requirements": json.dumps(record.requirements),
+                        "steps": json.dumps(record.steps),
+                        "failure_reason": record.failure_reason,
+                        "logs": json.dumps(
+                            [asdict(log) for log in record.logs], ensure_ascii=False
+                        ),
+                    }
+                )

_pyprodtest/observers/html_report/__init__.py

@@ -0,0 +1,5 @@
+"""Standalone HTML report observer."""
+
+from _pyprodtest.observers.html_report.html_observer import HtmlObserver
+
+__all__ = ["HtmlObserver"]