testerkit 0.4.0__py3-none-any.whl

testerkit/execution/instrument_events.py

@@ -0,0 +1,42 @@
+"""Runner-neutral instrument-event emission.
+
+Each runner emits ``InstrumentConnected`` events for the instruments
+its session resolved. The shape is the same across runners — only
+the source of the records differs (pytest reads
+``get_instrument_records()`` from the active state; OpenHTF reads
+its own plug registry, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from testerkit.data.events import InstrumentConnected
+from testerkit.execution.run_scope import (
+    RunScope,
+    instrument_cal_fields,
+    instrument_info_fields,
+)
+from testerkit.models.instrument import InstrumentRecord
+
+
+def emit_instrument_events(
+    logger: RunScope,
+    event_log: Any,
+    records: dict[str, InstrumentRecord],
+) -> None:
+    """Emit one ``InstrumentConnected`` event per resolved instrument."""
+    for role, rec in records.items():
+        event = InstrumentConnected(
+            session_id=logger._session_id,
+            run_id=logger.test_run.id,
+            role=role,
+            instrument_id=rec.instrument_id,
+            driver=rec.driver,
+            resource=rec.resource,
+            protocol=rec.protocol,
+            **instrument_info_fields(rec),
+            **instrument_cal_fields(rec),
+            mocked=rec.mocked,
+        )
+        event_log.emit(event)

testerkit/execution/limits.py

@@ -0,0 +1,154 @@
+"""Limit derivation from part specifications.
+
+This module provides functions to derive test limits from part
+characteristics and spec bands, including guardband application.
+"""
+
+from typing import Any
+
+from testerkit.models.capability import SpecBand
+from testerkit.models.enums import Comparator
+from testerkit.models.part import PartCharacteristic
+from testerkit.models.test_config import Limit
+
+
+def derive_limit(
+    char: PartCharacteristic,
+    conditions: dict[str, Any] | None = None,
+    guardband_pct: float = 0.0,
+    comparator: Comparator = Comparator.GELE,
+    limit_low: float | None = None,
+    limit_high: float | None = None,
+    char_id: str | None = None,
+) -> Limit:
+    """Derive test limit from characteristic at given conditions.
+
+    This function:
+    1. Finds the SpecBand matching the given conditions
+    2. Calculates bounds from value ± accuracy (or explicit limits)
+    3. Applies guardband to tighten the limits
+    4. Sets characteristic_id for structured traceability
+
+    Args:
+        char: The part characteristic containing spec values.
+        conditions: Operating point parameters (e.g., {"temperature": 25}).
+        guardband_pct: Percentage to tighten limits (0-100).
+        comparator: How to compare measured value against limits.
+        limit_low: Explicit low limit override.
+        limit_high: Explicit high limit override.
+        char_id: Optional characteristic ID for characteristic_id traceability.
+
+    Returns:
+        A Limit object with derived low/high bounds and characteristic_id.
+
+    Raises:
+        ValueError: If no SpecBand matches the given conditions.
+    """
+    params = conditions or {}
+
+    # Find matching spec band
+    band = char.get_spec_at(params)
+    if band is None:
+        cond_str = ", ".join(f"{k}={v}" for k, v in params.items())
+        avail = [dict(s.when) for s in char.bands]
+        raise ValueError(f"No spec band matches: {cond_str}. Available when clauses: {avail}")
+
+    # Calculate spec bounds from SpecBand
+    spec_low, spec_high = _calculate_bounds(band, comparator, limit_low, limit_high)
+
+    # Apply guardband (tighten limits)
+    final_low, final_high = _apply_guardband(spec_low, spec_high, guardband_pct, comparator.value)
+
+    characteristic_id = char_id
+    spec_ref = _build_spec_ref(char, params)
+
+    nominal = float(band.value) if isinstance(band.value, (int, float)) else None
+
+    return Limit(
+        low=final_low,
+        high=final_high,
+        nominal=nominal,
+        unit=char.unit or "",
+        comparator=comparator,
+        characteristic_id=characteristic_id,
+        spec_ref=spec_ref,
+    )
+
+
+def _calculate_bounds(
+    band: SpecBand,
+    comparator: Comparator,
+    limit_low: float | None,
+    limit_high: float | None,
+) -> tuple[float | None, float | None]:
+    """Calculate spec bounds from a SpecBand.
+
+    Priority:
+    1. Explicit limit_low/limit_high overrides
+    2. SpecBand.value ± SpecBand.accuracy (via total_uncertainty)
+    3. SpecBand.value alone (exact match)
+
+    For single-sided comparators (LE, GE), only the relevant bound is set.
+    """
+    # Explicit limits take precedence
+    if limit_low is not None or limit_high is not None:
+        return limit_low, limit_high
+
+    if band.value is None or not isinstance(band.value, (int, float)):
+        return None, None
+
+    val: float = band.value
+
+    # Single-sided comparators
+    if comparator in (Comparator.LE, Comparator.LT):
+        return None, val
+    if comparator in (Comparator.GE, Comparator.GT):
+        return val, None
+
+    # Range comparator: derive from accuracy
+    if band.accuracy is not None:
+        uncertainty = band.accuracy.total_uncertainty(val, val)
+        return val - uncertainty, val + uncertainty
+
+    # No accuracy — exact value
+    return val, val
+
+
+def _apply_guardband(
+    spec_low: float | None,
+    spec_high: float | None,
+    guardband_pct: float,
+    comparator: str,
+) -> tuple[float | None, float | None]:
+    """Apply guardband to tighten spec limits.
+
+    Guardband reduces the acceptable range by moving limits inward.
+    """
+    if guardband_pct == 0.0:
+        return spec_low, spec_high
+
+    range_comparators = {"GELE", "GELT", "GTLE", "GTLT"}
+
+    if comparator in range_comparators and spec_low is not None and spec_high is not None:
+        range_size = spec_high - spec_low
+        guardband_amount = range_size * guardband_pct / 100.0 / 2.0
+        return spec_low + guardband_amount, spec_high - guardband_amount
+
+    if comparator in {"LE", "LT"} and spec_high is not None:
+        guardband_amount = abs(spec_high) * guardband_pct / 100.0
+        return spec_low, spec_high - guardband_amount
+
+    if comparator in {"GE", "GT"} and spec_low is not None:
+        guardband_amount = abs(spec_low) * guardband_pct / 100.0
+        return spec_low + guardband_amount, spec_high
+
+    return spec_low, spec_high
+
+
+def _build_spec_ref(char: PartCharacteristic, conditions: dict[str, Any]) -> str:
+    """Build a spec reference string for traceability."""
+    base_ref = char.datasheet_ref or "spec"
+    if conditions:
+        cond_str = ", ".join(f"{k}={v}" for k, v in sorted(conditions.items()))
+        return f"{base_ref} @ {cond_str}"
+    return base_ref

testerkit/execution/metadata.py

@@ -0,0 +1,102 @@
+"""Runner-neutral run-metadata assembly.
+
+:class:`RunScope` takes a fat kwargs dict — UUT serial, station
+identity, part identity, fixture id, environment capture, project
+name, profile name + facets, session inputs, instrument records, etc.
+The dict is the same regardless of which runner is driving; only the
+*sources* differ (pytest reads CLI options + session fixtures, OpenHTF
+reads its config object, etc.).
+
+This module owns the assembly: :func:`build_run_metadata` takes
+already-resolved inputs and returns the kwargs dict ready to hand to
+:class:`RunScope`. Each runner's plugin gathers the inputs in its
+own way and calls in.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from testerkit.environment import capture_environment
+from testerkit.execution._git import get_project_name
+
+
+def build_run_metadata(
+    *,
+    uut_serial: str | None,
+    uut_part_number: str | None = None,
+    uut_revision: str | None = None,
+    uut_lot_number: str | None = None,
+    station_id: str | None = None,
+    station_config: Any | None = None,
+    fixture_config: Any | None = None,
+    part: Any | None = None,
+    operator_id: str | None = None,
+    project_dir: Path,
+    data_dir: str | None = None,
+    test_phase: str | None = None,
+    profile_name: str | None = None,
+    profile_facets: dict[str, str] | None = None,
+    session_inputs: dict[str, str] | None = None,
+    instrument_records: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the kwargs dict :class:`RunScope` expects.
+
+    Resolves derived fields (part info from the active ``part``,
+    station fields from ``station_config``, environment capture, git
+    project name) so the runner's plugin doesn't have to. ``uut_part_number``
+    and ``uut_revision`` fall back to the active part when not
+    supplied explicitly.
+    """
+    # Part identity from the active Part
+    part_id = part_name = part_revision = None
+    if part is not None:
+        part_id = part.id
+        part_name = part.name
+        part_revision = part.revision
+
+    # Fixture id
+    fixture_id = None
+    if fixture_config is not None:
+        fixture_id = getattr(fixture_config, "id", None) or getattr(fixture_config, "name", None)
+
+    # Station info
+    station_name = station_type = station_location = None
+    if station_config is not None:
+        station_name = station_config.name
+        station_type = getattr(station_config, "station_type", None) or getattr(
+            station_config, "type", None
+        )
+        station_location = station_config.location
+
+    # UUT defaults from part spec
+    if uut_part_number is None and part is not None:
+        uut_part_number = part.part_number
+    if uut_revision is None and part is not None:
+        uut_revision = part.revision
+
+    return {
+        "uut_serial": uut_serial,
+        "uut_part_number": uut_part_number,
+        "uut_revision": uut_revision,
+        "uut_lot_number": uut_lot_number,
+        "station_id": station_id,
+        "station_name": station_name,
+        "station_type": station_type,
+        "station_location": station_location,
+        "operator_id": operator_id,
+        "part_id": part_id,
+        "part_name": part_name,
+        "part_revision": part_revision,
+        "fixture_id": fixture_id,
+        "project_name": get_project_name(project_dir),
+        "project_dir": project_dir,
+        "data_dir": data_dir,
+        "test_phase": test_phase,
+        "profile": profile_name,
+        "profile_facets": dict(profile_facets or {}),
+        "session_inputs": dict(session_inputs or {}),
+        "instruments": instrument_records,
+        "environment": capture_environment(),
+    }

testerkit/execution/mocks.py

@@ -0,0 +1,63 @@
+"""Runner-neutral mock installation.
+
+Given a merged dict of ``{target: MockEntry}`` and runner-specific
+callbacks for fixture resolution + cleanup registration, install
+each mock via :func:`unittest.mock.patch.object` and bind teardown
+to the runner's per-test cleanup hook.
+
+The runner provides:
+
+* ``resolve_fixture(name) -> Any | None`` — return the fixture value,
+  or ``None`` if it doesn't exist on this test (callback emits a
+  warning and skips).
+* ``register_cleanup(callable)`` — register a zero-arg cleanup that
+  fires when the test completes (pytest: ``request.addfinalizer``;
+  unittest: ``addCleanup``; OpenHTF: phase teardown).
+
+This module owns the unittest.mock interaction so each runner can
+share the same mock-lifecycle without copy-pasting.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import Any
+
+from testerkit.models.test_config import MockEntry
+
+
+def install_mocks(
+    by_target: dict[str, MockEntry],
+    *,
+    resolve_fixture: Callable[[str], Any],
+    register_cleanup: Callable[[Callable[[], None]], None],
+    fixture_lookup_error: type[Exception] = LookupError,
+) -> None:
+    """Install each mock and register its teardown.
+
+    ``by_target`` is the de-duplicated merged map (later scopes
+    overwrite earlier ones by target — caller does the cascade).
+    Each :class:`MockEntry`'s ``target`` is ``"<fixture>.<attr>"``;
+    the callback resolves the fixture, this function patches the
+    attribute and binds cleanup. Missing fixtures emit a warning
+    (caught via ``fixture_lookup_error`` from the runner's host) and
+    skip — a typo in ``target`` shouldn't fail the run, just record.
+    """
+    from unittest.mock import patch as _patch
+
+    for target, entry in by_target.items():
+        fixture_name, _, attr = target.partition(".")
+        try:
+            fixture_value = resolve_fixture(fixture_name)
+        except fixture_lookup_error:
+            warnings.warn(
+                f"testerkit_mocks target {target!r}: fixture {fixture_name!r} not "
+                "found on this test — mock skipped. Check the entry `target:` "
+                "matches a fixture in the test's signature.",
+                stacklevel=2,
+            )
+            continue
+        patcher = _patch.object(fixture_value, attr, **entry.patch_kwargs())
+        patcher.start()
+        register_cleanup(patcher.stop)