interface-test-kit 0.1.0__py3-none-any.whl

interface_test_kit/profile.py

@@ -0,0 +1,178 @@
+"""Test profiles: one YAML file per product variant."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .checks import STEP_TYPES
+
+_TOP_REQUIRED = {"name", "version", "steps"}
+_TOP_OPTIONAL = {"setup", "detect", "serial_number", "reference", "max_attempts"}
+_DETECT_KEYS = {"dmi_product_name", "devicetree_model"}
+_STEP_COMMON = {"type", "name", "id", "equipment"}
+
+
+@dataclass(frozen=True)
+class Step:
+    id: str
+    name: str
+    type: str
+    config: Any
+    equipment: str | None
+    line: int
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    version: int
+    steps: list[Step]
+    setup: str = ""
+    detect: dict[str, str] = field(default_factory=dict)
+    serial_pattern: str | None = None
+    reference: bool = False
+    max_attempts: int = 4
+    path: Path | None = None
+
+
+class ProfileError(Exception):
+    def __init__(self, message: str, line: int | None = None):
+        self.message = message
+        self.line = line
+        super().__init__(f"line {line}: {message}" if line else message)
+
+
+def slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+def _step_lines(root: yaml.Node) -> list[int]:
+    if isinstance(root, yaml.MappingNode):
+        for key, value in root.value:
+            if key.value == "steps" and isinstance(value, yaml.SequenceNode):
+                return [item.start_mark.line + 1 for item in value.value]
+    return []
+
+
+def _key_line(root: yaml.Node, name: str) -> int | None:
+    if isinstance(root, yaml.MappingNode):
+        for key, _ in root.value:
+            if key.value == name:
+                return key.start_mark.line + 1
+    return None
+
+
+def _parse_step(index: int, raw: Any, line: int | None) -> Step:
+    label = f"steps[{index}]"
+    if not isinstance(raw, dict):
+        raise ProfileError(f"{label}: must be a mapping", line)
+    if isinstance(raw.get("name"), str) and raw["name"].strip():
+        label += f" ({raw['name']})"
+    try:
+        if "name" not in raw or not str(raw["name"]).strip():
+            raise ValueError("name: missing")
+        if "type" not in raw:
+            raise ValueError("type: missing")
+        check = STEP_TYPES.get(raw["type"])
+        if check is None:
+            raise ValueError(f"type: unknown step type '{raw['type']}' "
+                             f"(known: {', '.join(sorted(STEP_TYPES))})")
+        name = str(raw["name"])
+        step_id = str(raw.get("id") or slug(name))
+        equipment = raw.get("equipment")
+        config = check.parse({"name": name,
+                              **{k: v for k, v in raw.items() if k not in _STEP_COMMON}})
+    except ValueError as e:
+        raise ProfileError(f"{label}: {e}", line) from None
+    return Step(step_id, name, raw["type"], config,
+                str(equipment) if equipment is not None else None, line or 0)
+
+
+def load_profile(path: Path) -> Profile:
+    path = Path(path)
+    text = path.read_text()
+    try:
+        root = yaml.compose(text, Loader=yaml.SafeLoader)
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        mark = getattr(e, "problem_mark", None)
+        raise ProfileError(f"invalid YAML: {getattr(e, 'problem', e)}",
+                           mark.line + 1 if mark else None) from None
+    if not isinstance(data, dict):
+        raise ProfileError("a profile must be a mapping with name, version and steps")
+
+    def err(key: str, message: str) -> ProfileError:
+        return ProfileError(f"{key}: {message}", _key_line(root, key))
+
+    for key in data:
+        if key not in _TOP_REQUIRED and key not in _TOP_OPTIONAL:
+            raise err(key, f"unknown field '{key}'")
+    for key in sorted(_TOP_REQUIRED):
+        if key not in data:
+            raise ProfileError(f"{key}: missing")
+    if not isinstance(data["name"], str) or not data["name"].strip():
+        raise err("name", "must be a non-empty text")
+    version = data["version"]
+    if not isinstance(version, int) or isinstance(version, bool) or version < 1:
+        raise err("version", "must be a whole number of 1 or more")
+    max_attempts = data.get("max_attempts", 4)
+    if not isinstance(max_attempts, int) or isinstance(max_attempts, bool) \
+            or not 1 <= max_attempts <= 10:
+        raise err("max_attempts", "must be a whole number from 1 to 10")
+    reference = data.get("reference", False)
+    if not isinstance(reference, bool):
+        raise err("reference", "must be true or false")
+    setup = data.get("setup", "") or ""
+    if not isinstance(setup, str):
+        raise err("setup", "must be a text")
+    detect = data.get("detect") or {}
+    if not isinstance(detect, dict):
+        raise err("detect", "must be a mapping")
+    for key in detect:
+        if key not in _DETECT_KEYS:
+            raise err("detect", f"unknown key '{key}' (known: {', '.join(sorted(_DETECT_KEYS))})")
+    pattern = None
+    if "serial_number" in data:
+        sn = data["serial_number"]
+        if not isinstance(sn, dict) or set(sn) - {"pattern"}:
+            raise err("serial_number", "must be a mapping with a pattern")
+        pattern = sn.get("pattern")
+        try:
+            re.compile(str(pattern))
+        except re.error as e:
+            raise err("serial_number", f"pattern is not a valid regular expression ({e})") from None
+    steps_raw = data["steps"]
+    if not isinstance(steps_raw, list) or not steps_raw:
+        raise err("steps", "must be a non-empty list")
+
+    lines = _step_lines(root)
+    steps: list[Step] = []
+    seen: set[str] = set()
+    for i, raw in enumerate(steps_raw):
+        line = lines[i] if i < len(lines) else None
+        step = _parse_step(i, raw, line)
+        if step.id in seen:
+            raise ProfileError(f"steps[{i}] ({step.name}): duplicate step id '{step.id}' "
+                               "(give the step a different name or an id)", line)
+        seen.add(step.id)
+        steps.append(step)
+
+    return Profile(name=data["name"], version=version, steps=steps, setup=setup,
+                   detect={k: str(v) for k, v in detect.items()},
+                   serial_pattern=str(pattern) if pattern is not None else None,
+                   reference=reference, max_attempts=max_attempts, path=path)
+
+
+def load_profiles(directory: Path) -> list[Profile]:
+    profiles = []
+    for path in sorted(Path(directory).glob("*.yaml")):
+        try:
+            profiles.append(load_profile(path))
+        except ProfileError as e:
+            raise ProfileError(f"{path}: {e}") from None
+    return sorted(profiles, key=lambda p: p.name)

interface_test_kit/profiles/demo.yaml

@@ -0,0 +1,22 @@
+# Profile for `itk demo`: a simulated EPC-24 variant B panel PC.
+name: EPC-24 variant B (demo)
+version: 1
+detect: {dmi_product_name: EPC-24B}
+serial_number: {pattern: "^EPC-24-\\d{5}$"}
+setup: >-
+  Plug the loopback plugs into COM1 and COM2, the two test sticks into the
+  blue USB ports, the network cable into LAN1 and the CAN cable between CAN0 and CAN1.
+steps:
+  - {type: serial, name: Serial 1, port: /dev/ttyS0, loopback: 9pin-full, bauds: [9600, 115200]}
+  - {type: serial, name: Serial 2, port: /dev/ttyS1, loopback: 9pin}
+  - type: usb
+    name: USB
+    count: 2
+    ports: [1-1, 2-1]
+    size_mb: 8
+    min_write_mbs: 10
+    min_read_mbs: 20
+    min_speed_mbps: 5000
+  - {type: ethernet, name: LAN1, iface: eth0, speed: 1000, duplex: full, ping: 192.168.100.1}
+  - {type: can, name: CAN, pair: [can0, can1], bitrate: 500000}
+  - {type: confirm, name: Power LED, prompt: "Is the power LED green?"}

interface_test_kit/report.py

@@ -0,0 +1,142 @@
+"""Write run reports to the network drive, or spool them locally until it is back."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+
+from .model import RunResult
+from .station import Station
+
+
+def folder_name(run: RunResult) -> str:
+    stamp = run.started.strftime("%Y%m%d-%H%M%S")
+    if run.mode == "selftest":
+        name = f"selftest_{run.station}_{stamp}"
+    else:
+        # a scanner glitch can deliver hundreds of characters; keep names well below 255 bytes
+        parts = [run.serial_number[:60]] + ([run.rma[:40]] if run.rma else []) + [stamp]
+        name = "_".join(parts)
+    name = re.sub(r"[^A-Za-z0-9._-]", "_", name)
+    return "_" + name if name.startswith(".") else name
+
+
+def _relative(run: RunResult) -> Path:
+    folder = folder_name(run)
+    return Path("selftest", folder) if run.mode == "selftest" else Path(folder)
+
+
+def report_reachable(station: Station) -> bool:
+    target = Path(station.report_dir)
+    if not target.is_dir() or not os.access(target, os.W_OK | os.X_OK):
+        return False
+    if station.mount_point is not None:
+        # An unmounted share leaves an empty local folder behind; writing there
+        # would put the report on the local disk without anyone noticing.
+        mount = Path(station.mount_point).resolve()
+        if not os.path.ismount(mount):
+            return False
+        if mount != target.resolve() and mount not in target.resolve().parents:
+            return False
+    return True
+
+
+def _fmt(value: float) -> str:
+    return f"{value:g}"
+
+
+def render_text(run: RunResult) -> str:
+    lines = [f"Interface test report ({'equipment self-test' if run.mode == 'selftest' else 'unit test'})",
+             "", f"Serial number: {run.serial_number}"]
+    if run.rma:
+        lines.append(f"RMA: {run.rma}")
+    lines.append(f"Profile: {run.profile_name} v{run.profile_version}")
+    lines.append(f"Station: {run.station}")
+    if run.operator:
+        lines.append(f"Operator: {run.operator}")
+    lines.append(f"Started: {run.started.isoformat(timespec='seconds')}")
+    if run.finished:
+        lines.append(f"Finished: {run.finished.isoformat(timespec='seconds')}")
+    lines.append(f"Tool version: {run.tool_version}")
+    if run.only:
+        lines.append(f"Only steps: {', '.join(run.only)}")
+    lines += [f"Result: {run.status}", ""]
+    for step in run.steps:
+        note = " (passed after retry)" if step.passed_after_retry else ""
+        msg = f" — {step.message}" if step.message else ""
+        lines.append(f"[{step.status}] {step.name}{msg}{note}")
+        if step.equipment_id:
+            lines.append(f"    Equipment: {step.equipment_id}")
+        for m in step.attempts[-1].measurements if step.attempts else []:
+            limits = []
+            if m.low is not None:
+                limits.append(f">= {_fmt(m.low)}")
+            if m.high is not None:
+                limits.append(f"<= {_fmt(m.high)}")
+            limit = f" (limit {' and '.join(limits)})" if limits else ""
+            unit = f" {m.unit}" if m.unit else ""
+            lines.append(f"    {m.name}: {_fmt(m.value)}{unit}{limit} "
+                         f"{'ok' if m.passed else 'out of limits'}")
+        if len(step.attempts) > 1:
+            for i, a in enumerate(step.attempts, 1):
+                lines.append(f"    attempt {i}: {a.status}{' — ' + a.message if a.message else ''}")
+        for a in step.attempts:
+            for d in a.details:
+                lines.append(f"        {d}")
+    return "\n".join(lines) + "\n"
+
+
+def _new_dir(path: Path) -> Path:
+    """Create ``path``, or ``path-2``, ``path-3``... so no earlier report is overwritten."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    for n in range(1, 1000):
+        candidate = path if n == 1 else path.with_name(f"{path.name}-{n}")
+        try:
+            candidate.mkdir()
+            return candidate
+        except FileExistsError:
+            continue
+    raise OSError(f"too many reports named {path.name}")
+
+
+def _write_into(base: Path, run: RunResult) -> Path:
+    path = _new_dir(base / _relative(run))
+    (path / "result.json").write_text(json.dumps(run.to_dict(), indent=2) + "\n")
+    (path / "report.txt").write_text(render_text(run))
+    return path
+
+
+def write_run(run: RunResult, station: Station) -> tuple[Path, bool]:
+    """Returns the folder written and whether it went to the local spool."""
+    if report_reachable(station):
+        try:
+            return _write_into(Path(station.report_dir), run), False
+        except OSError:
+            pass
+    return _write_into(Path(station.spool_dir), run), True
+
+
+def _spooled_runs(spool: Path) -> list[Path]:
+    if not spool.is_dir():
+        return []
+    return sorted(p.parent for p in spool.rglob("result.json"))
+
+
+def sync_spool(station: Station) -> list[Path]:
+    spool = Path(station.spool_dir)
+    runs = _spooled_runs(spool)
+    if not runs or not report_reachable(station):
+        return []
+    moved = []
+    for src in runs:
+        try:
+            dest = _new_dir(Path(station.report_dir) / src.relative_to(spool))
+            shutil.copytree(src, dest, dirs_exist_ok=True)
+        except OSError:
+            continue
+        shutil.rmtree(src, ignore_errors=True)
+        moved.append(dest)
+    return moved

interface_test_kit/runner.py

@@ -0,0 +1,71 @@
+"""Run the steps of a profile, applying the retry rule."""
+
+from __future__ import annotations
+
+from .checks import STEP_TYPES
+from .context import Context
+from .model import Attempt, StepResult
+from .profile import Profile, Step
+from .ui import UI
+
+RETRY_PROMPT = "Retry this step?"
+CONFIRM_INFO = "Passed. Running once more to confirm."
+INTERNAL_ERROR = "Internal error in this test step. Tell the test engineer."
+
+
+def _attempt(step: Step, ctx: Context, ui: UI) -> Attempt:
+    try:
+        return STEP_TYPES[step.type].run(step.config, ctx, ui)
+    except KeyboardInterrupt:
+        raise
+    except Exception as e:  # a broken check must not stop the run
+        return Attempt.fail(INTERNAL_ERROR, details=[f"{type(e).__name__}: {e}"])
+
+
+def _passed(attempts: list[Attempt]) -> bool:
+    if len(attempts) == 1:
+        return attempts[0].status == "PASS"
+    return attempts[-1].status == "PASS" and attempts[-2].status == "PASS"
+
+
+def run_step(step: Step, ctx: Context, ui: UI, max_attempts: int) -> StepResult:
+    """A step passes on its first attempt, or when its last two attempts passed."""
+    attempts = [_attempt(step, ctx, ui)]
+    while not _passed(attempts) and len(attempts) < max_attempts:
+        if attempts[-1].status == "FAIL":
+            if not ui.ask_yes_no(f"{attempts[-1].message}\n{RETRY_PROMPT}"):
+                break
+        else:
+            ui.info(CONFIRM_INFO)
+        attempts.append(_attempt(step, ctx, ui))
+    status = "PASS" if _passed(attempts) else "FAIL"
+    return StepResult(step.id, step.name, step.type, status, attempts)
+
+
+def select_steps(profile: Profile, only: list[str] | None = None) -> list[Step]:
+    """The profile's steps, limited to the ids in ``only`` (case-insensitive)."""
+    if not only:
+        return list(profile.steps)
+    wanted = [o.lower() for o in only]
+    known = {s.id.lower() for s in profile.steps}
+    for o in wanted:
+        if o not in known:
+            raise ValueError(f"unknown step id: {o}")
+    return [s for s in profile.steps if s.id.lower() in wanted]
+
+
+def run_steps(profile: Profile, ctx: Context, ui: UI, only: list[str] | None = None,
+              results: list[StepResult] | None = None) -> list[StepResult]:
+    """Finished steps are appended to ``results`` as they complete, so a caller
+    still has them when the operator aborts with Ctrl+C."""
+    results = [] if results is None else results
+    for step in select_steps(profile, only):
+        equipment_id = None
+        if ctx.mode == "selftest" and step.equipment:
+            equipment_id = ui.ask_text(f"{step.equipment}: ")
+        ui.step_started(step)
+        result = run_step(step, ctx, ui, profile.max_attempts)
+        result.equipment_id = equipment_id
+        ui.step_finished(result)
+        results.append(result)
+    return results

interface_test_kit/session.py

@@ -0,0 +1,110 @@
+"""One operator session: serial number, profile, preflight, steps, result and report."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+
+from . import __version__
+from .context import Context
+from .detect import detect_profiles
+from .model import RunResult, StepResult
+from .profile import Profile, load_profiles
+from .report import sync_spool, write_run
+from .runner import run_steps, select_steps
+from .station import Station
+from .ui import UI
+
+SERIAL_PROMPT = "Scan or enter the serial number: "
+SERIAL_RETRY = "The serial number does not match the expected format. Try again."
+SELFTEST_HINT = "Same failure on several units? Run the equipment self-test."
+
+
+def real_context(mode: str) -> Context:
+    from .checks.can import open_socketcan
+    from .checks.serial import open_pyserial
+    return Context(open_serial=open_pyserial, open_can=open_socketcan, mode=mode)
+
+
+def _ask_serial(ui: UI, pattern: str | None) -> str:
+    while True:
+        serial = ui.ask_text(SERIAL_PROMPT)
+        if serial and (pattern is None or re.fullmatch(pattern, serial)):
+            return serial
+        ui.info(SERIAL_RETRY)
+
+
+def _choose(ui: UI, candidates: list[Profile]) -> Profile:
+    for i, p in enumerate(candidates, 1):
+        ui.info(f"  {i}  {p.name} (v{p.version})")
+    while True:
+        answer = ui.ask_text("Choose the profile number: ")
+        if answer.isdigit() and 1 <= int(answer) <= len(candidates):
+            return candidates[int(answer) - 1]
+        ui.info(f"Enter a number from 1 to {len(candidates)}.")
+
+
+def _select_profile(ui: UI, ctx: Context, candidates: list[Profile]) -> Profile:
+    detected = detect_profiles(candidates, ctx) if len(candidates) > 1 else candidates
+    profile = detected[0] if len(detected) == 1 else _choose(ui, candidates)
+    while not ui.ask_yes_no(f"Profile: {profile.name} (v{profile.version}). Correct?"):
+        if len(candidates) == 1:
+            raise ValueError("Profile not confirmed. Check the profiles with the test engineer.")
+        profile = _choose(ui, candidates)
+    return profile
+
+
+def run_session(station: Station, ctx: Context, ui: UI, *, rma: str | None = None,
+                only: list[str] | None = None, profiles: list[Profile] | None = None) -> RunResult:
+    moved = sync_spool(station)
+    if moved:
+        ui.info(f"Uploaded {len(moved)} saved report(s) to the network drive.")
+
+    selftest = ctx.mode == "selftest"
+    if profiles is None:
+        profiles = load_profiles(station.profile_dir)
+    candidates = [p for p in profiles if p.reference == selftest]
+    if not candidates:
+        kind = "reference profiles" if selftest else "profiles"
+        raise ValueError(f"No {kind} found in {station.profile_dir}")
+
+    # The serial pattern is per profile; with several candidates we only know it
+    # after the profile is chosen, so ask first and check against all patterns.
+    patterns = {p.serial_pattern for p in candidates}
+    pattern = patterns.pop() if len(patterns) == 1 else None
+    serial = "selftest" if selftest else _ask_serial(ui, pattern)
+    operator = ui.ask_text("Operator: ") if station.ask_operator else None
+    profile = _select_profile(ui, ctx, candidates)
+    if not selftest and profile.serial_pattern and not re.fullmatch(profile.serial_pattern, serial):
+        ui.info(SERIAL_RETRY)
+        serial = _ask_serial(ui, profile.serial_pattern)
+
+    steps = select_steps(profile, only)
+    run = RunResult(ctx.mode, serial, rma, profile.name, profile.version, station.name, operator,
+                    datetime.now().astimezone(), None, __version__, [], "ABORTED", only)
+
+    from .checks import STEP_TYPES
+    problems = [p for s in steps for p in STEP_TYPES[s.type].preflight(s.config, ctx)]
+    if problems:
+        for p in problems:
+            ui.info(p)
+    else:
+        results: list[StepResult] = run.steps
+        try:
+            if profile.setup:
+                ui.wait_key(profile.setup + "\nPress Enter when ready.")
+            run_steps(profile, ctx, ui, only, results=results)
+            run.status = "PASS" if all(s.status == "PASS" for s in results) else "FAIL"
+        except KeyboardInterrupt:
+            run.status = "ABORTED"
+
+    run.finished = datetime.now().astimezone()
+    ui.banner(run.status)
+    if run.status == "FAIL" and not selftest:
+        ui.info(SELFTEST_HINT)
+    path, spooled = write_run(run, station)
+    if spooled:
+        ui.info(f"Network drive not reachable. Report saved locally: {path}")
+    else:
+        ui.info(f"Report saved: {path}")
+    return run

interface_test_kit/sim/__init__.py

@@ -0,0 +1 @@
+"""Simulated interfaces for tests and ``itk demo``."""

interface_test_kit/sim/can.py

@@ -0,0 +1,40 @@
+"""A simulated CAN network: frames sent on one interface arrive at all other open ones."""
+
+from __future__ import annotations
+
+from collections import deque
+
+
+class SimCanBus:
+    def __init__(self, network: "SimCanNetwork", iface: str):
+        self.network = network
+        self.iface = iface
+        self.queue: deque = deque()
+
+    def send(self, arb_id: int, data: bytes, extended: bool) -> None:
+        self.network.deliver(self, (arb_id, bytes(data), extended))
+
+    def recv(self, timeout: float):
+        return self.queue.popleft() if self.queue else None
+
+    def close(self) -> None:
+        if self in self.network.buses:
+            self.network.buses.remove(self)
+
+
+class SimCanNetwork:
+    def __init__(self, drop: set[str] | None = None):
+        self.drop = set(drop or ())
+        self.buses: list[SimCanBus] = []
+
+    def open(self, iface: str) -> SimCanBus:
+        bus = SimCanBus(self, iface)
+        self.buses.append(bus)
+        return bus
+
+    def deliver(self, sender: SimCanBus, frame) -> None:
+        if sender.iface in self.drop:
+            return
+        for bus in self.buses:
+            if bus is not sender:
+                bus.queue.append(frame)

interface_test_kit/sim/fakes.py

@@ -0,0 +1,64 @@
+"""Fake system pieces: a command runner and sysfs trees under a fake root."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from ..context import CommandResult
+
+
+class FakeRunner:
+    """Answers commands by their first two words; records every call."""
+
+    def __init__(self, responses: dict[str, CommandResult] | None = None):
+        self.responses = dict(responses or {})
+        self.calls: list[list[str]] = []
+
+    def __call__(self, args: list[str]) -> CommandResult:
+        self.calls.append(list(args))
+        key = " ".join(args[:2])
+        if key in self.responses:
+            response = self.responses[key]
+            return response(args) if callable(response) else response
+        return CommandResult(127, "", f"fake: no response for {key}")
+
+
+def lsblk_result(nodes: list[dict]) -> CommandResult:
+    return CommandResult(0, json.dumps({"blockdevices": nodes}), "")
+
+
+def add_usb_stick(root: Path, kname: str, label: str | None, port: str, speed: int,
+                  mountpoint: str | None, tran: str = "usb") -> dict:
+    """Create the sysfs entries of a USB stick partition and return its lsblk disk node."""
+    disk = re.sub(r"\d+$", "", kname)
+    bus = port.split("-")[0]
+    dev = root / f"sys/devices/pci0000:00/0000:00:14.0/usb{bus}/{port}"
+    dev.mkdir(parents=True, exist_ok=True)
+    (dev / "speed").write_text(f"{speed}\n")
+    (dev / "devnum").write_text("2\n")
+    part = dev / f"{port}:1.0/host0/target0:0:0/0:0:0:0/block/{disk}/{kname}"
+    part.mkdir(parents=True, exist_ok=True)
+    links = root / "sys/class/block"
+    links.mkdir(parents=True, exist_ok=True)
+    (links / kname).symlink_to(part)
+    if mountpoint:
+        (root / mountpoint.lstrip("/")).mkdir(parents=True, exist_ok=True)
+    return {"name": disk, "kname": disk, "path": f"/dev/{disk}", "label": None,
+            "mountpoint": None, "tran": tran,
+            "children": [{"name": kname, "kname": kname, "path": f"/dev/{kname}", "label": label,
+                          "mountpoint": mountpoint, "tran": None}]}
+
+
+def add_netdev(root: Path, iface: str, carrier: int | None = 1, speed: int | None = 1000,
+               duplex: str | None = "full", hardware: bool = True) -> Path:
+    """Create /sys/class/net/<iface>; None leaves the attribute unreadable like a down link."""
+    d = root / "sys/class/net" / iface
+    d.mkdir(parents=True, exist_ok=True)
+    for name, value in (("carrier", carrier), ("speed", speed), ("duplex", duplex)):
+        if value is not None:
+            (d / name).write_text(f"{value}\n")
+    if hardware:
+        (d / "device").mkdir(exist_ok=True)
+    return d

interface_test_kit/sim/serial.py

@@ -0,0 +1,44 @@
+"""A simulated serial port with a loopback plug, optionally broken."""
+
+from __future__ import annotations
+
+
+class SimLoopback:
+    def __init__(self, wiring: dict[str, tuple[str, ...]], broken_lines: set[str] | None = None,
+                 data_fault: str | None = None):
+        self.wiring = wiring
+        self.broken_lines = set(broken_lines or ())
+        self.data_fault = data_fault
+        self.outputs = {"RTS": False, "DTR": False}
+        self.buffer = bytearray()
+        self.baud = 0
+
+    def set_baud(self, baud: int) -> None:
+        self.baud = baud
+
+    def write(self, data: bytes) -> None:
+        if self.data_fault == "no_echo":
+            return
+        data = bytearray(data)
+        if self.data_fault == "corrupt" and len(data) > 100:
+            data[100] ^= 0x01
+        self.buffer += data
+
+    def read(self, n: int, timeout: float) -> bytes:
+        out = bytes(self.buffer[:n])
+        del self.buffer[:n]
+        return out
+
+    def reset_input(self) -> None:
+        self.buffer.clear()
+
+    def set_line(self, name: str, state: bool) -> None:
+        self.outputs[name] = state
+
+    def get_line(self, name: str) -> bool:
+        return any(self.outputs.get(out, False)
+                   for out, inputs in self.wiring.items()
+                   if name in inputs and f"{out}->{name}" not in self.broken_lines)
+
+    def close(self) -> None:
+        pass