testerkit 0.4.0__py3-none-any.whl

testerkit/execution/accessors.py

@@ -0,0 +1,54 @@
+"""Instrument accessors for test functions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from testerkit.execution._state import get_current_step_aliases
+from testerkit.models.instrument import InstrumentRecord
+
+
+def _instrument_not_found(alias: str, target: str, instruments: dict[str, Any]) -> KeyError:
+    """Build a KeyError for a missing instrument, listing available roles."""
+    available = ", ".join(sorted(instruments)) or "(none)"
+    if alias != target:
+        return KeyError(
+            f"Alias '{alias}' targets '{target}' which is not in "
+            f"station instruments. Available: {available}"
+        )
+    return KeyError(f"No instrument with role '{alias}'. Available: {available}")
+
+
+class InstrumentAccessor:
+    """Callable accessor for instruments by role, with type-based grouping."""
+
+    def __init__(self, instruments: dict[str, Any], records: dict[str, InstrumentRecord]):
+        self._instruments = instruments
+        self._records = records
+
+    def _current_aliases(self) -> dict[str, str]:
+        """Get current step aliases from the active ContextVar."""
+        return get_current_step_aliases()
+
+    def __call__(self, role: str) -> Any:
+        """Get instrument by role name, resolving aliases. Raises KeyError with available roles."""
+        aliases = self._current_aliases()
+        resolved = aliases.get(role, role)
+        if resolved not in self._instruments:
+            raise _instrument_not_found(role, resolved, self._instruments)
+        return self._instruments[resolved]
+
+    def by_type(self, driver_path: str) -> dict[str, Any]:
+        """Get all instruments matching a driver class import path."""
+        return {
+            role: self._instruments[role]
+            for role, record in self._records.items()
+            if record.driver == driver_path and role in self._instruments
+        }
+
+    def roles(self) -> list[str]:
+        """List available instrument role names, including active aliases."""
+        aliases = self._current_aliases()
+        names = set(self._instruments.keys())
+        names.update(aliases.keys())
+        return sorted(names)

testerkit/execution/audit.py

@@ -0,0 +1,51 @@
+"""Runner-neutral traceability audit.
+
+Walks the just-completed step's measurements and reports any that
+are missing required traceability fields. Works for any runner that
+records measurements through :class:`RunScope` — pytest, OpenHTF,
+unittest wrappers all share this check.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def audit_traceability(logger_inst: Any, *, strict: bool, spec_active: bool) -> None:
+    """Check the current step's measurements for traceability completeness.
+
+    Walks measurements recorded during the just-completed test and
+    flags any that lack required fields:
+
+    * ``step_path`` — always required (populated by the runner's step
+      wrapper).
+    * ``spec_ref`` OR ``uut_pin`` — required only when ``spec_active``
+      is True (i.e. a part spec is loaded for the session). Runs
+      without a spec exercise the graceful-degradation path and are
+      not penalized for lacking pin/spec references.
+
+    In ``strict`` mode, raises :class:`AssertionError` if any
+    measurement is incomplete so the test fails. Otherwise returns
+    silently — the caller decides whether to surface the issues.
+    """
+    steps = getattr(getattr(logger_inst, "test_run", None), "steps", None)
+    if not steps:
+        return
+    step = steps[-1]
+
+    incomplete: list[str] = []
+    for vec in step.vectors:
+        for m in vec.measurements:
+            missing: list[str] = []
+            if not m.step_path:
+                missing.append("step_path")
+            if spec_active and not m.spec_ref and not m.uut_pin:
+                missing.append("spec_ref/uut_pin")
+            if missing:
+                incomplete.append(f"{m.name}: missing {', '.join(missing)}")
+
+    if incomplete and strict:
+        raise AssertionError(
+            "--strict-traceability: measurements missing required fields:\n  "
+            + "\n  ".join(incomplete)
+        )

testerkit/execution/cascade.py

@@ -0,0 +1,85 @@
+"""Runner-neutral cascade walk — sidecar + profile → merged :class:`TestEntry`.
+
+Re-exports :func:`testerkit.execution.sidecar.merged_test_entry` and adds
+:func:`cascade_for` that combines sidecar lookup, profile lookup, and
+merge into a single call. Each runner's plugin invokes this once per
+test to get the typed :class:`TestEntry` it needs to inject markers
+from.
+
+Inputs are runner-neutral (a :class:`SidecarConfig` and the active
+:class:`ProfileConfig`, plus class / function names). Pytest's
+plugin reads the sidecar via ``load_sidecar(module_file)`` and the
+profile via ``get_active_profile()``; another runner reads its
+host's equivalents and calls the same function.
+
+Also exposes :func:`find_unmatched_profile_keys` — a profile typo
+detector. A profile that lists ``tests.test_typo`` when no test by
+that name exists in the collected suite is a production-screen
+silent no-op; warn loudly. The runner's plugin gathers the test IDs
+its host collected and asks this module which profile keys map to
+nothing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from testerkit.execution.sidecar import _merge_entry_into, merged_test_entry
+from testerkit.models.project import ProfileConfig
+from testerkit.models.test_config import SidecarConfig, TestEntry
+
+__all__ = ["cascade_for", "find_unmatched_profile_keys", "merged_test_entry"]
+
+
+def cascade_for(
+    sidecar: SidecarConfig | None,
+    profile: ProfileConfig | None,
+    cls_name: str | None,
+    func_name: str | None,
+) -> TestEntry:
+    """Build the merged :class:`TestEntry` for one test.
+
+    Cascade order: sidecar (file → class → leaf) then profile
+    (root → class → leaf), with last-wins per field. Either source
+    may be ``None``.
+    """
+    merged = TestEntry()
+    if sidecar is not None:
+        _merge_entry_into(merged, merged_test_entry(sidecar, cls_name, func_name))
+    if profile is not None:
+        _merge_entry_into(merged, merged_test_entry(profile, cls_name, func_name))
+    return merged
+
+
+def find_unmatched_profile_keys(
+    profile: ProfileConfig,
+    test_ids: Iterable[tuple[str | None, str]],
+) -> list[str]:
+    """Return profile.tests keys that match no collected test.
+
+    ``test_ids`` is the iterable of ``(class_name, func_name)`` pairs
+    the runner collected. Classless module-level tests pass
+    ``class_name=None``. Returns formatted ``profile.tests[...]``
+    paths in declared order — caller emits a warning if non-empty.
+    """
+    func_names: set[str] = set()
+    methods_by_class: dict[str, set[str]] = {}
+    class_names: set[str] = set()
+    for cls_name, func_name in test_ids:
+        func_names.add(func_name)
+        if cls_name is not None:
+            class_names.add(cls_name)
+            methods_by_class.setdefault(cls_name, set()).add(func_name)
+
+    unmatched: list[str] = []
+    for key, entry in profile.tests.items():
+        if key in class_names:
+            for nested_key in entry.tests:
+                if nested_key in methods_by_class[key]:
+                    continue
+                unmatched.append(f"  profile.tests[{key!r}].tests[{nested_key!r}]")
+            continue
+        if key in func_names:
+            continue
+        unmatched.append(f"  profile.tests[{key!r}]")
+    return unmatched

testerkit/execution/connections.py

@@ -0,0 +1,491 @@
+"""Resolve ``testerkit_characteristics`` / ``testerkit_connections`` markers to fixture connections.
+
+The two markers compose into a single ordered list of
+:class:`FixtureConnection` instances that the test body iterates via
+``ctx.connections``. ``testerkit_characteristics`` supplies the
+characteristic list (each char's ``resolved_pins``);
+``testerkit_connections`` supplies an explicit named-connection list or
+an instrument-channel selector. When both are present the connection
+list narrows the union of chars' pin sets; when only one is present
+the resolver derives the iteration set from it directly.
+
+Pulled out of ``plugin.py`` so that file stays focused on pytest hook
+registration. The pytest fixture wrapping this resolver
+(``_testerkit_resolve_connections``) lives in ``plugin.py``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import KeysView, Sequence, ValuesView
+from contextvars import Token
+from typing import TYPE_CHECKING, Any
+
+from testerkit.execution._state import (
+    push_active_characteristic,
+    push_active_connection,
+    reset_active_characteristic,
+    reset_active_connection,
+)
+from testerkit.models.test_config import FixtureConfig, FixtureConnection
+
+if TYPE_CHECKING:
+    import pytest
+
+
+class ConnectionResolutionError(Exception):
+    """Raised when ``testerkit_characteristics`` / ``testerkit_connections`` cannot resolve.
+
+    Runner-neutral: the pytest adapter catches this and re-raises as
+    ``ConnectionResolutionError`` at the fixture boundary; other runners adapt
+    to their own user-error type.
+    """
+
+
+class ConnectionIterator:
+    """Iterable + name-addressable view over the bound :class:`FixtureConnection` list.
+
+    Built by ``_testerkit_resolve_connections`` from a test's spec/connections markers.
+    The instance is iterable (drives the ``_active_connection_var``
+    ContextVar so drivers can route to the *current* connection) and
+    also supports ``__getitem__`` / ``keys()`` / ``values()`` /
+    ``__contains__`` for passive name lookup. Iteration is single-use
+    and follows insertion order; lookup never pushes the ContextVar.
+    """
+
+    def __init__(
+        self,
+        connections: list[FixtureConnection],
+        conn_to_char: dict[str, str] | None = None,
+        _parent: ConnectionIterator | None = None,
+    ) -> None:
+        self._connections = connections
+        self._by_name: dict[str, FixtureConnection] = {c.name: c for c in connections}
+        # Per-connection char lookup, keyed by connection name. Built
+        # by ``resolve_test_connections`` from the spec; empty when no
+        # chars are in scope (pure ``testerkit_connections`` bringup).
+        self._conn_to_char: dict[str, str] = conn_to_char or {}
+        # Parent iterator (for ``for_characteristic`` sub-iterators) so
+        # iterating the child also marks the parent ``started`` —
+        # actual iteration, not iterator construction, is what the
+        # consumption guard cares about.
+        self._parent: ConnectionIterator | None = _parent
+        self._idx = 0
+        self._conn_token: Token[FixtureConnection | None] | None = None
+        self._char_token: Token[str | None] | None = None
+        self.started = False
+
+    def __iter__(self) -> ConnectionIterator:
+        return self
+
+    def __next__(self) -> FixtureConnection:
+        self._reset_tokens()
+        if self._idx >= len(self._connections):
+            raise StopIteration
+        connection = self._connections[self._idx]
+        self._idx += 1
+        self.started = True
+        if self._parent is not None:
+            self._parent.started = True
+        self._conn_token = push_active_connection(connection)
+        char = self._conn_to_char.get(connection.name)
+        if char is not None:
+            self._char_token = push_active_characteristic(char)
+        return connection
+
+    def __len__(self) -> int:
+        return len(self._connections)
+
+    def __getitem__(self, key: str | int) -> FixtureConnection:
+        if isinstance(key, int):
+            return self._connections[key]
+        return self._by_name[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._by_name
+
+    def keys(self) -> KeysView[str]:
+        return self._by_name.keys()
+
+    def values(self) -> ValuesView[FixtureConnection]:
+        return self._by_name.values()
+
+    def for_characteristic(self, char_id: str) -> ConnectionIterator:
+        """Return a fresh iterator scoped to connections owned by ``char_id``.
+
+        Iterates only the subset whose ``conn_to_char`` mapping matches
+        ``char_id``. Each ``__next__`` pushes the active-char ContextVar
+        to ``char_id`` (so ``verify`` stamps the right
+        ``characteristic_id``) AND marks the parent iterator
+        ``started`` — so the consumption guard in
+        ``_testerkit_resolve_connections`` sees real iteration, not just
+        iterator construction. Building a sub-iterator and never
+        iterating it does NOT count as consumption.
+        """
+        subset = [
+            conn for conn in self._connections if self._conn_to_char.get(conn.name) == char_id
+        ]
+        return ConnectionIterator(subset, {c.name: char_id for c in subset}, _parent=self)
+
+    def _reset_tokens(self) -> None:
+        if self._char_token is not None:
+            reset_active_characteristic(self._char_token)
+            self._char_token = None
+        if self._conn_token is not None:
+            reset_active_connection(self._conn_token)
+            self._conn_token = None
+
+    def cleanup(self) -> None:
+        """Pop any lingering active-connection / active-char tokens on teardown."""
+        self._reset_tokens()
+
+
+def _per_char_pins(characteristics: Sequence[str], spec_ctx: Any) -> dict[str, list[str]]:
+    """Return per-char ``resolved_pins`` lists, validating each char.
+
+    Keys preserve user-listed order; values are each char's pin list.
+    Raises if the spec context is missing or a char is unknown.
+    """
+    if spec_ctx is None:
+        raise ConnectionResolutionError(
+            f"testerkit_characteristics({list(characteristics)!r}) "
+            "requires a part (load via --part=<id-or-path> / parts/ auto-discovery)."
+        )
+    out: dict[str, list[str]] = {}
+    for char_id in characteristics:
+        char = spec_ctx.part.characteristics.get(char_id)
+        if char is None:
+            raise ConnectionResolutionError(
+                f"Characteristic {char_id!r} not found in part {spec_ctx.part.id!r}."
+            )
+        out[char_id] = list(char.resolved_pins)
+    return out
+
+
+def _pick_connection_for_pin(
+    pin_id: str,
+    target_function: Any,
+    pin_net: str | None,
+    fixture_cfg: FixtureConfig,
+) -> FixtureConnection | None:
+    """Pick the fixture connection that routes ``(pin, function)``.
+
+    Match priority, highest first:
+
+    1. **Exact**: char's ``function`` and conn's ``function`` are both set
+       and equal — the strongest match.
+    2. **Pin-only**: at least one side has no ``function``. Either the
+       char doesn't declare what function it needs (backward-compatible
+       with pre-function fixtures) or the conn is generic
+       (function-unset). The first such conn for the pin wins.
+
+    Connections where both sides set ``function`` but the values differ
+    are skipped — a wired-up DC connection isn't valid for an AC char.
+    Match by ``uut_pin`` first; falls back to net match when
+    ``uut_pin`` is unset on the connection.
+    """
+    exact_match: FixtureConnection | None = None
+    pin_only_match: FixtureConnection | None = None
+    for conn in fixture_cfg.connections.values():
+        pin_hit = conn.uut_pin == pin_id or (pin_net is not None and conn.net == pin_net)
+        if not pin_hit:
+            continue
+        if target_function is not None and conn.function == target_function:
+            exact_match = exact_match or conn
+        elif target_function is None or conn.function is None:
+            # At least one side is None — pin-only fallback.
+            pin_only_match = pin_only_match or conn
+        # else: both sides set but different — skip (e.g. char wants
+        # ac_voltage but this conn is dc_voltage-only).
+    return exact_match or pin_only_match
+
+
+def _resolve_chars_to_connections(
+    characteristics: Sequence[str],
+    spec_ctx: Any,
+    fixture_cfg: FixtureConfig,
+) -> tuple[list[FixtureConnection], dict[str, str]]:
+    """Match each char's ``(pin, function)`` against the fixture.
+
+    Returns a deduplicated connection list (preserving char order, then
+    char-pin order) plus a ``conn_name → char_id`` lookup. When the
+    same fixture connection is selected by multiple chars, the
+    first-listing char owns it (matching marker order).
+
+    Edge case: when two chars share a pin but neither declares
+    ``function:`` (or both share the same function), they bind to the
+    same connection — only the first-listed char owns it in
+    ``conn_to_char``. ``ctx.connections.for_characteristic(<later_char>)``
+    will return an empty subset for the loser. To avoid this, declare
+    distinct ``function:`` values on the chars and the matching
+    connections (the per-function tie-break in
+    :func:`_pick_connection_for_pin`), or put the chars on different
+    pins.
+    """
+    matched: list[FixtureConnection] = []
+    conn_to_char: dict[str, str] = {}
+    seen_names: set[str] = set()
+    for char_id in characteristics:
+        char = spec_ctx.part.characteristics.get(char_id)
+        if char is None:
+            continue
+        for pin_id in char.resolved_pins:
+            pin = spec_ctx.part.pins.get(pin_id)
+            net = pin.net if pin else None
+            conn = _pick_connection_for_pin(pin_id, char.function, net, fixture_cfg)
+            if conn is None or conn.name in seen_names:
+                continue
+            matched.append(conn)
+            conn_to_char[conn.name] = char_id
+            seen_names.add(conn.name)
+    return matched, conn_to_char
+
+
+def _resolve_connections_payload(
+    mark: Any,
+) -> tuple[list[str] | None, dict[str, Any] | None]:
+    """Return ``(names, instrument_channels)`` from a ``testerkit_connections`` mark.
+
+    The marker is a shape-discriminated one-of:
+
+    * Positional list of strings → bind by fixture-connection name
+      (``@pytest.mark.testerkit_connections(["vout_measure"])``).
+    * Kwargs by instrument name → bind by instrument → channel selectors
+      (``@pytest.mark.testerkit_connections(dmm=["ch1"])``).
+
+    Exactly one shape may appear per marker invocation. Pydantic already
+    enforces the one-of at the YAML layer (``TestEntry.connections`` is a
+    ``list[str] | dict[str, Any]`` discriminated union); this function
+    is the parallel guard for the inline-marker call site.
+    """
+    args = list(getattr(mark, "args", ()) or ())
+    kwargs = dict(getattr(mark, "kwargs", {}) or {})
+    if args and kwargs:
+        raise ConnectionResolutionError(
+            "testerkit_connections takes EITHER a positional list of "
+            "connection names OR instrument kwargs, not both. Got "
+            f"args={args!r} kwargs={kwargs!r}."
+        )
+    if args:
+        positional: Any = args[0] if len(args) == 1 else None
+        if not isinstance(positional, list):
+            raise ConnectionResolutionError(
+                "testerkit_connections positional form takes one list of "
+                f"connection names. Got {args!r}."
+            )
+        names: list[Any] = positional
+        if not all(isinstance(n, str) for n in names):
+            raise ConnectionResolutionError(
+                f"testerkit_connections names must be strings; got {names!r}."
+            )
+        return [str(n) for n in names], None
+    if kwargs:
+        return None, kwargs
+    raise ConnectionResolutionError(
+        "testerkit_connections requires either a positional list of "
+        "connection names or instrument kwargs."
+    )
+
+
+def _named_connections(
+    names: list[str],
+    fixture_cfg: FixtureConfig | None,
+    char_pins: set[str] | None,
+) -> list[FixtureConnection]:
+    """Resolve ``connections=[name, ...]`` against the fixture, in user-listed order."""
+    if fixture_cfg is None:
+        raise ConnectionResolutionError(
+            "testerkit_connections(connections=...) requires a fixture config; "
+            "connection names are only meaningful relative to a fixture YAML."
+        )
+    resolved: list[FixtureConnection] = []
+    for name in names:
+        conn = fixture_cfg.connections.get(name)
+        if conn is None:
+            raise ConnectionResolutionError(
+                f"Fixture connection {name!r} not found in fixture config."
+            )
+        resolved.append(conn)
+    if char_pins is not None:
+        invalid = [conn.name for conn in resolved if conn.uut_pin not in char_pins]
+        if invalid:
+            raise ConnectionResolutionError(
+                f"testerkit_connections names {invalid} resolve to pins outside "
+                f"the union of declared characteristics' pin sets {sorted(char_pins)}."
+            )
+    return resolved
+
+
+def _channel_selectors(
+    instrument_channels: dict[str, Any],
+    fixture_cfg: FixtureConfig | None,
+    char_pins: set[str] | None,
+) -> list[FixtureConnection]:
+    """Resolve ``instrument_channels={inst: [chs]}`` in user-listed order.
+
+    With a fixture, matches each (instrument, channel) selector against
+    fixture connections; with ``char_pins`` set, every match must be in
+    that pin set. Without a fixture, synthesizes minimal
+    :class:`FixtureConnection` stubs from the (instrument, channel)
+    tuples — usable for early bringup where the UUT-pin mapping isn't
+    yet captured.
+    """
+    if fixture_cfg is None:
+        stubs: list[FixtureConnection] = []
+        for inst_name, channels in instrument_channels.items():
+            if channels == "all":
+                raise ConnectionResolutionError(
+                    f"testerkit_connections instrument_channels[{inst_name!r}]='all' "
+                    "requires a fixture config."
+                )
+            for ch in channels:
+                ch_str = str(ch)
+                stubs.append(
+                    FixtureConnection(
+                        name=f"{inst_name}_ch{ch_str}",
+                        instrument=inst_name,
+                        instrument_channel=ch_str,
+                    )
+                )
+        return stubs
+
+    matched: list[FixtureConnection] = []
+    for inst_name, channels in instrument_channels.items():
+        if channels == "all":
+            inst_matches = [
+                conn for conn in fixture_cfg.connections.values() if conn.instrument == inst_name
+            ]
+        else:
+            inst_matches = []
+            for ch in channels:
+                ch_str = str(ch)
+                hit = next(
+                    (
+                        conn
+                        for conn in fixture_cfg.connections.values()
+                        if conn.instrument == inst_name and conn.instrument_channel == ch_str
+                    ),
+                    None,
+                )
+                if hit is None:
+                    raise ConnectionResolutionError(
+                        f"testerkit_connections instrument_channels[{inst_name!r}]={ch_str!r} "
+                        "matched no fixture connection."
+                    )
+                inst_matches.append(hit)
+        matched.extend(inst_matches)
+
+    if char_pins is not None:
+        invalid = [
+            f"{conn.instrument}/{conn.instrument_channel}"
+            for conn in matched
+            if conn.uut_pin not in char_pins
+        ]
+        if invalid:
+            raise ConnectionResolutionError(
+                f"testerkit_connections selected channels {invalid} resolve to pins outside "
+                f"the union of declared characteristics' pin sets {sorted(char_pins)}."
+            )
+    return matched
+
+
+def resolve_test_connections(
+    characteristics: Sequence[str],
+    conn_marker: pytest.Mark | None,
+    spec_ctx: Any,
+    fixture_cfg: FixtureConfig | None,
+) -> tuple[list[FixtureConnection], dict[str, str]]:
+    """Resolve the iterable connection set + per-connection char lookup.
+
+    The two markers compose:
+
+    * **chars only** — derive connections from each char's
+      ``(pin, function)``, matched against the fixture. Empty list
+      when ``characteristics`` is empty AND no ``conn_marker``.
+    * **connections only** — explicit lookup against the fixture, or
+      synthesized stubs when ``instrument_channels`` is given without
+      a fixture.
+    * **chars + connections** — connections narrows the union of the
+      chars' pin sets. Iteration order follows the user-listed
+      connections; every selected connection must lie within the
+      union pin set. Fixtureless ``instrument_channels`` with
+      characteristics in scope is rejected — there is no ``uut_pin``
+      to validate against (drop the characteristics for pure bringup,
+      or load a fixture).
+
+    Returns a tuple of ``(connections, conn_to_char)`` where
+    ``conn_to_char`` maps each connection's ``name`` to the char that
+    owns it (used by ``ConnectionIterator`` to push the active-char
+    ContextVar per connection). The lookup is empty for the
+    pure-``testerkit_connections`` bringup case.
+    """
+    if not characteristics and conn_marker is None:
+        return [], {}
+
+    per_char_pins: dict[str, list[str]] = {}
+    if characteristics:
+        per_char_pins = _per_char_pins(characteristics, spec_ctx)
+
+    if conn_marker is None:
+        if fixture_cfg is None:
+            # Chars in scope but no fixture loaded → ctx.connections is
+            # an empty iterator. Tests that only resolve limits (and
+            # never iterate connections) work fine in this mode; tests
+            # that DO iterate trip the post-run "declared but didn't
+            # consume" guard in _testerkit_resolve_connections.
+            return [], {}
+        return _resolve_chars_to_connections(characteristics, spec_ctx, fixture_cfg)
+
+    union_pins: set[str] | None = None
+    if per_char_pins:
+        union_pins = {pin for pins in per_char_pins.values() for pin in pins}
+
+    names, instrument_channels = _resolve_connections_payload(conn_marker)
+    if names is not None:
+        connections = _named_connections(names, fixture_cfg, union_pins)
+    else:
+        assert instrument_channels is not None
+        # Tighten bug #15: chars in scope + fixtureless instrument_channels
+        # would silently bypass the per-char pin-set cross-check (no
+        # uut_pin to validate against). That makes testerkit_characteristics
+        # dead weight in this branch — flag it loud.
+        if characteristics and fixture_cfg is None:
+            raise ConnectionResolutionError(
+                f"testerkit_characteristics({list(characteristics)!r}) cannot "
+                "validate fixtureless instrument_channels selectors — there "
+                "is no uut_pin to cross-check against. Drop "
+                "testerkit_characteristics for pure bringup, or load a "
+                "fixture."
+            )
+        connections = _channel_selectors(instrument_channels, fixture_cfg, union_pins)
+
+    conn_to_char = _connections_to_char_map(connections, per_char_pins, spec_ctx)
+    return connections, conn_to_char
+
+
+def _connections_to_char_map(
+    connections: list[FixtureConnection],
+    per_char_pins: dict[str, list[str]],
+    spec_ctx: Any,
+) -> dict[str, str]:
+    """Build the ``conn.name → char_id`` lookup for explicit ``testerkit_connections`` paths.
+
+    For each connection, pick the first char (in user-declared order)
+    whose pin set covers the connection's ``uut_pin``. Connections
+    outside any char's pin set (only possible for fixtureless
+    ``instrument_channels`` stubs without a spec) get no entry.
+    """
+    if not per_char_pins:
+        return {}
+    out: dict[str, str] = {}
+    for conn in connections:
+        pin_id = conn.uut_pin
+        if pin_id is None and spec_ctx is not None and conn.net is not None:
+            net_pins = spec_ctx.part.get_pins_by_net(conn.net)
+            pin_id = net_pins[0] if net_pins else None
+        if pin_id is None:
+            continue
+        for char_id, pins in per_char_pins.items():
+            if pin_id in pins:
+                out[conn.name] = char_id
+                break
+    return out