testerkit 0.4.0__py3-none-any.whl

testerkit/_docs/reference/pytest/fixtures.md

@@ -0,0 +1,342 @@
+# TesterKit fixtures
+
+The bundled pytest plugin registers a set of public fixtures. Take any of them in a test's signature; pytest resolves and injects them by name. Names beginning with `_` are internal and may change without notice.
+
+This page is the comprehensive reference. For a guided introduction see the [tutorial](../../tutorial/); for the seven `@pytest.mark.testerkit_*` markers see [TesterKit markers](markers.md).
+
+## At a glance
+
+Grouped by what you reach for the fixture **for**:
+
+| Group | What you'd reach for it for | Fixtures |
+|---|---|---|
+| Recording measurements | Write a measurement row, resolve a limit, raise on FAIL, prompt the operator | `verify`, `measure`, `limits`, `prompt` |
+| Recording outputs & streams | Record a read-back value, or append samples to a channel | `observe`, `stream` |
+| Talking to instruments | Get a driver instance, route a signal, hit a UUT pin | `instruments`, `instrument`, `instrument_records`, `uut`, `pins`, `routes`, `fixture_manager` |
+| Reading per-test state | Active sweep params, observations, the connection currently being iterated | `context`, `connections` |
+| Reading loaded configuration | The typed YAML / CLI that shaped this run | `part`, `station_config`, `fixture_config`, `run_context`, `mock_instruments` |
+| Flow control | Drive the test body's iteration / synchronization | `vectors`, `sync` |
+
+Plus **one role-named fixture per instrument the station YAML declares** (e.g. `dmm`, `psu`, `scope`). See [Per-role auto-fixtures](#per-role-auto-fixtures).
+
+Every fixture above is available in every test — pytest will resolve any of them by name. The "what you'd reach for it for" column is intent, not availability. Several have meaningful "no project state" defaults (`part` returns `None`, `instruments` returns `{}`, `connections` returns `None`, etc.) so taking one in a vanilla project is safe.
+
+---
+
+## Recording measurements
+
+The verbs you write into test bodies. Most tests need `verify` and nothing else from this group.
+
+### `verify` — function
+
+Callable: `verify(name, value, limit=None, characteristic=None)`. Records the measurement row (value, units, limits, traceability), resolves a limit from the active chain (sidecar / inline marker / part spec), stamps `measurement_outcome`, and **raises `AssertionError`** when the value is out of range.
+
+`limit=` accepts either a `Limit` model or a dict literal — `verify` coerces dicts via `Limit.model_validate(...)`.
+
+```python
+def test_rail(dmm, verify):
+    verify("output_voltage", dmm.measure_dc_voltage())            # limit resolves from sidecar/marker
+
+def test_rail_inline(dmm, verify):
+    verify("vout", dmm.measure_dc_voltage(),
+           limit={"low": 3.2, "high": 3.4, "unit": "V"})          # inline dict literal
+```
+
+Same record-side effect as `measure`; the only difference is `verify` raises on FAIL. Use `verify` when a fail should stop the line. With no resolvable limit, `verify` raises `MissingLimitError` — unless the active profile sets `verify_requires_limit: false`, in which case it falls back to `measure` semantics (record-only, `Outcome.DONE`).
+
+### `measure` — function
+
+Callable: `measure(name, value, limit=None, characteristic=None)`. The record-only sibling of `verify` — records a measurement row with `outcome = DONE` and **never raises**, even when no limit resolves. Use it when a value should be captured but not pass/fail judged (characterization, diagnostics, sweeps you plot post-hoc).
+
+```python
+def test_voltage(dmm, measure):
+    v = dmm.measure_dc_voltage()
+    measure("output_voltage", v, limit={"low": 3.2, "high": 3.4, "unit": "V"})
+```
+
+`limit=` accepts either a `Limit` model or a dict literal. Same recording path as `verify`, just no FAIL-side effect — use it when a failing measurement shouldn't abort the test.
+
+### `limits` — function
+
+Read-only `name → Limit` mapping for the current test, resolved from the same chain as `verify`. Use for ad-hoc pythonic assertions:
+
+```python
+def test_inline_check(dmm, limits):
+    v = dmm.measure_dc_voltage()
+    assert v in limits["output_voltage"]
+```
+
+`limits[name]` raises `KeyError` when no limit is configured — there is no silent default.
+
+### `prompt` — function
+
+Returns a callable that resolves operator prompts declared via `@pytest.mark.testerkit_prompts`:
+
+```python
+@pytest.mark.testerkit_prompts(
+    inspect={"message": "Verify LED is GREEN", "prompt_type": "confirm"},
+)
+def test_visual(prompt, verify):
+    prompt("inspect")  # blocks until operator responds
+    verify("led_state", read_led_color())
+```
+
+See [`testerkit_prompts`](markers.md#testerkit_prompts) for the marker shape.
+
+---
+
+## Recording outputs & streams
+
+The verbs for read-back values and continuous samples. Like `verify`/`measure`, these are callable fixtures — take the name in the test signature, then call it. Each wraps the matching `context` method.
+
+### `observe` — function
+
+Callable: `observe(name, value, *, namespace=None, unit=None)`. Records a read-back value (the response side — a measured output, not a pass/fail judgment) onto the active vector. The value's shape decides where it lands: scalars stay inline; arrays / `Waveform` go to the ChannelStore; blobs go to the FileStore — with a `channel://` / `file://` reference stamped on the vector.
+
+```python
+def test_rail(dmm, observe, verify):
+    observe("v_rail", dmm.measure_dc_voltage())   # output, recorded not judged
+    observe("scope_cap", scope.capture())          # Waveform → ChannelStore
+```
+
+See [the three verbs](../../concepts/data/three-verbs.md) for how a value routes to the right store by shape.
+
+### `stream` — function
+
+Callable: `stream(name, sample, *, namespace=None, unit=None) -> str`. Appends one sample to a named channel timeline (continuous capture). Returns the `channel://` reference. Use it for a live sensor feed or free-running acquisition, where the channel — not the individual call — is the unit you query later.
+
+```python
+def test_soak(dmm, stream):
+    for _ in range(n):
+        stream("supply_rail", dmm.measure_dc_voltage(), unit="V")
+```
+
+---
+
+## Talking to instruments
+
+These fixtures need a station YAML to produce useful results. Without one they return empty dicts / `None`.
+
+### `instruments` — session
+
+Yields `dict[role_name, driver_instance]`. Connects every instrument declared in the station YAML at session start, disconnects at session end. Auto-mocks when `--mock-instruments` is on. Identity and calibration are checked against config for real hardware.
+
+```python
+def test_voltage(instruments):
+    dmm = instruments["dmm"]
+    assert dmm.measure_dc_voltage() > 3.0
+```
+
+In most tests you take **role names directly** as fixtures (`def test_x(dmm, psu)`) — see [Per-role auto-fixtures](#per-role-auto-fixtures) — and never need `instruments` itself.
+
+### `instrument` — function
+
+Returns an `InstrumentAccessor` for role-keyed access with grouping:
+
+```python
+def test_one(instrument):
+    dmm = instrument("dmm")
+
+def test_all(instrument):
+    dmms = instrument.by_type("pymeasure.instruments.keithley.Keithley2000")
+```
+
+### `instrument_records` — session
+
+Returns `dict[role_name, InstrumentRecord]` — the resolved instrument metadata (driver class, resource string, calibration cert, mocked flag) before connection. Useful for tests that need identity or calibration info without taking the live driver.
+
+### `uut` — session
+
+Yields the connected UUT driver (resolved from `Part.driver` + `FixtureConfig.uut_resource`), or `None` when the part has no driver. Mocked when `--mock-instruments` is on.
+
+```python
+def test_firmware(uut):
+    assert uut.get_version().startswith("2.")
+```
+
+### `pins` — session
+
+Returns a `PinAccessor` for UUT-centric pin access. Looks up the instrument that the fixture YAML maps to each UUT pin, transparently activates the route if any switch is in the path.
+
+```python
+def test_output(pins):
+    pins["VIN"].set_voltage(5.0)
+    pins["VIN"].enable_output()
+    assert pins["VOUT"].measure_voltage() > 3.0
+```
+
+Raises `pytest.UsageError` if no fixture config or instruments are loaded.
+
+### `routes` — function
+
+Yields a `RouteManager` for explicit switch routing, or `None` when no routes exist:
+
+```python
+def test_vout(dmm, routes):
+    with routes.for_pin("VOUT"):
+        v = dmm.measure_voltage()
+```
+
+`routes.deactivate_all()` runs automatically at test teardown.
+
+### `fixture_manager` — session
+
+Returns the `FixtureManager` directly, for the rare test that needs advanced lookup (e.g. net-name → connection) beyond what `pins` exposes:
+
+```python
+def test_lookup(fixture_manager):
+    conn = fixture_manager.get_connection_for_net("VOUT_3V3")
+    inst = fixture_manager.get_instrument_for_connection(conn.name)
+```
+
+---
+
+## Reading per-test state
+
+The active vector's params, observations, and the connection currently being iterated.
+
+### `context` — function
+
+Returns a `Context` exposing the run / UUT / station / vector state for the active test. Resolves on every test, with empty defaults when there's nothing to expose.
+
+| Method | Returns | Purpose |
+|---|---|---|
+| `context.get_param(name, default=None)` | `Any` | Read a sweep / parametrize value. |
+| `context.params` | `dict` | All active params for this row. |
+| `context.changed(key)` | `bool` | True if `key` differs from prior iteration. |
+| `context.last(key, default=None)` | `Any` | Prior iteration's value for `key`. |
+| `context.observe(key, value)` | `None` | Record a free-form observation. |
+| `context.observations` | `dict` | All recorded observations. |
+| `context.part` | `Part \| None` | Active part definition (= `part` fixture). |
+| `context.station` | `StationConfig \| None` | Active station config (= `station_config` fixture). |
+| `context.run` | `TestRun \| None` | The current `TestRun`. |
+| `context.limits` | `LimitsView` | Read-only view of the active limits. |
+| `context.characteristics` | `tuple[str, ...]` | Active characteristic IDs from `testerkit_characteristics`. |
+
+```python
+def test_rail(context, psu, dmm, verify):
+    psu.set_voltage(context.get_param("vin", 5.0))
+    verify("vout", dmm.measure_dc_voltage())
+```
+
+### `connections` — function
+
+Returns the `ConnectionIterator` resolved from `testerkit_characteristics` / `testerkit_connections` markers, or `None` when no markers are declared.
+
+```python
+def test_per_pin(connections, dmm):
+    for conn in connections:
+        v = dmm.measure_voltage()
+```
+
+---
+
+## Reading loaded configuration
+
+Typed accessors over the YAML / CLI that shaped this run. Each one resolves to its model OR `None` (or an empty dict / bool) — taking one in a vanilla project is safe.
+
+### `part` — session
+
+Returns the active `Part` definition loaded from `parts/*.yaml` (identity, pins, characteristics), or `None` if no `parts/` directory or no match. For derived limits use the `limits` fixture or `context.get_limit(name)`.
+
+Resolution chain (first match wins):
+1. `--part <id-or-path>` — `<id>` looks up `parts/<id>.yaml`; `<path>` is used directly.
+2. `--uut-part-number <pn>` — content match against `part.part_number:` across `parts/*.yaml`.
+3. Single-file fallback when `parts/` holds exactly one part file.
+4. `None`.
+
+```python
+def test_spec(part, context, dmm, verify):
+    if part:
+        assert part.part_number == "DEMO-BUCK-3V3"
+    verify("output_voltage", dmm.measure_dc_voltage())  # limit resolves from the part spec
+```
+
+### `station_config` — session
+
+Returns the `StationConfig` resolved from `--station` / `stations/*.yaml`, or `None`. Also publishes the value to the active-station ContextVar so `context.station` works without taking the fixture.
+
+### `fixture_config` — session
+
+Returns the `FixtureConfig` resolved from `--fixture` / `fixtures/*.yaml`, or `None`. In worker mode (multi-site), extracts just this site's `connections` and `uut_resource`.
+
+### `run_context` — session
+
+Returns the `RunContext` for the active run. Use it to attach run-level metadata that persists across tests:
+
+```python
+def test_setup(run_context):
+    run_context.set("operator_badge", "EMP-12345")
+    run_context.set("fixture_serial", "FIX-001")
+```
+
+For per-test or per-vector state, use `context` instead.
+
+### `mock_instruments` — session
+
+Returns `bool`. True when `--mock-instruments` was passed or `TESTERKIT_MOCK_INSTRUMENTS=1` is set. The same flag drives the `instruments` fixture's behavior; tests rarely take it directly except for diagnostic branches.
+
+---
+
+## Flow control
+
+Two fixtures that drive the test body's iteration shape, not just expose data. `vectors` collapses pytest's per-row case multiplication into one in-body loop; `sync` blocks the body until peer workers reach the same named point.
+
+### `vectors` — function
+
+Taking `vectors` in the test signature switches collection to **self-loop mode**: the function-level vector sources (`@pytest.mark.parametrize`, function-level `testerkit_sweeps`, sidecar `sweeps:`, profile overrides) are consolidated into one matrix at collection time, and the test runs as a single pytest case. (Class- or module-level `testerkit_sweeps` still fan out as separate pytest cases — one per outer condition — each running the consolidated inner matrix.) The test body iterates the matrix itself:
+
+```python
+def test_sweep(vectors, psu, dmm, measure):
+    for v in vectors:
+        psu.set_voltage(v["vin"])
+        measure("vout", dmm.measure_dc_voltage())
+```
+
+Each `for` iteration pushes the row's params + index into active state so `measure`, `verify`, and `context` see the same row-scoped context they would in normal (one-case-per-row) mode. The fixture fails the test at teardown if the matrix is non-empty but the body iterated zero times.
+
+Choose self-loop mode when an outer setup (thermal soak, supply ramp) shouldn't repeat per row; choose normal parametrize mode when you want pytest to report one case per row.
+
+### `sync` — session
+
+Yields a `SyncPoint` for multi-UUT coordination when running in worker mode (`_TESTERKIT_SITE_INDEX` is set), or `None` in single-site mode. `sync.wait(name, timeout=...)` blocks until every site reaches the same name:
+
+```python
+def test_measure_hot(dmm, sync):
+    if sync:
+        sync.wait("thermal_soak", timeout=300)
+    v = dmm.measure_voltage()
+```
+
+---
+
+## Per-role auto-fixtures
+
+When the plugin finds a station YAML at `pytest_configure`, it dynamically registers one session-scoped fixture per `instruments:` role. A station YAML like
+
+```yaml
+instruments:
+  dmm: keithley_dmm_001
+  psu: keysight_psu_002
+  scope: tek_dpo_003
+```
+
+exposes `dmm`, `psu`, and `scope` as fixtures, each returning the connected driver for that role:
+
+```python
+def test_rail(dmm, psu, verify):
+    psu.set_voltage(5.0)
+    verify("vout", dmm.measure_dc_voltage())
+```
+
+These names are not hard-coded — they come from your station YAML at session start.
+
+---
+
+## See also
+
+- [TesterKit markers](markers.md) — the seven `@pytest.mark.testerkit_*` decorators and their sidecar equivalents
+- [pytest-native reference](../overview/pytest-native.md) — how the bundled plugin uses pytest's own collection / fixtures / markers
+- [Models](../data/models.md) — `Limit`, `MeasurementLimitConfig`, `PartContext`, `StationConfig`, `FixtureConfig` field shapes
+- [Test vectors & sweeps](../../how-to/execution/vector-expansion.md) — `testerkit_sweeps`, `parametrize`, and the `vectors` self-loop fixture
+- [Spec-driven testing](../../how-to/execution/spec-driven-testing.md) — `testerkit_characteristics` + `connections` workflow

testerkit/_docs/reference/pytest/index.md

@@ -0,0 +1,12 @@
+# Reference — pytest plugin
+
+The fixtures and markers the bundled pytest plugin contributes on top of stock pytest. For pytest-native mechanics (collection, parametrize, conftest, CLI flags), see [pytest-native](../overview/pytest-native.md).
+
+- [Fixtures](fixtures.md) — all the fixtures the plugin contributes, with signatures, scopes, and per-fixture examples
+- [Markers](markers.md) — the seven `@pytest.mark.testerkit_*` decorators and their 1:1 sidecar equivalents
+
+## See also
+
+- [Concepts → pytest](../../concepts/overview/pytest.md) — why the platform rides on pytest as the primary runner
+- [How-to → Writing tests](../../how-to/execution/writing-tests.md) — task recipes for authoring tests that use these fixtures + markers
+- [Reference → Configuration](../configuration.md) — sidecar YAML schemas (the YAML form of every marker)

testerkit/_docs/reference/pytest/markers.md

@@ -0,0 +1,257 @@
+# TesterKit markers
+
+The TesterKit pytest plugin registers **seven markers**. Each maps 1:1 to a field on `TestEntry` (the recursive node type in the sidecar YAML), so anything you can write inline as a marker, you can write in the sidecar — and vice versa.
+
+Pytest's own markers (`@pytest.mark.parametrize`, `@pytest.mark.skip`, `@pytest.mark.flaky` from `pytest-rerunfailures`, etc.) work unchanged. TesterKit's markers slot in alongside them.
+
+## No-stacking rule
+
+At most one inline `@pytest.mark.testerkit_X` decorator of each kind per test. Multi-entry payloads (a list of dicts for sweeps/mocks, multiple kwargs for limits/prompts) consolidate onto one marker. `@pytest.mark.parametrize` is the explicit exception — pytest's native stacking convention stays. Stacking a TesterKit marker raises `StackedMarkersError` at collection.
+
+```python
+# OK
+@pytest.mark.testerkit_sweeps([{"temperature": [-40, 25, 85], "load": [0.1, 0.5]}])
+def test_x(...): ...
+
+# Not OK — raises StackedMarkersError
+@pytest.mark.testerkit_sweeps([{"temperature": [-40, 25, 85]}])
+@pytest.mark.testerkit_sweeps([{"load": [0.1, 0.5]}])
+def test_x(...): ...
+```
+
+---
+
+## `testerkit_limits`
+
+Pin a `Limit` per measurement name. Both `verify(name, value)` and `measure(name, value)` record the measurement row and resolve the limit against this marker (or the sidecar's `limits:` block, or the active part spec, in resolution order); the only difference is `verify` raises `AssertionError` on FAIL where `measure` doesn't.
+
+**Signature:** `@pytest.mark.testerkit_limits(**by_name)` — one keyword per measurement name; each value is a dict matching `MeasurementLimitConfig`.
+
+```python
+@pytest.mark.testerkit_limits(
+    output_voltage={"low": 3.135, "high": 3.465, "unit": "V"},
+    output_current={"high": 0.5, "unit": "A"},
+)
+def test_power_rail(dmm, psu, verify):
+    verify("output_voltage", dmm.measure_dc_voltage())
+    verify("output_current", psu.measure_current())
+```
+
+**Sidecar equivalent:**
+
+```yaml
+limits:
+  output_voltage: {low: 3.135, high: 3.465, unit: V}
+  output_current: {high: 0.5, unit: A}
+```
+
+**Full shape:** `low`, `high`, `nominal`, `unit`, `comparator`, plus the alternative `characteristic:` / `tolerance_pct:` / `tolerance_abs:` derivation, and the `bands:` list for condition-indexed limits. See [`MeasurementLimitConfig`](../data/models.md) for the full schema and [Test limits](../../how-to/execution/limits.md#condition-indexed-bands) for the band semantics.
+
+---
+
+## `testerkit_sweeps`
+
+TesterKit-native parametrize. Each entry in the list is one **axis-group dict** — single-key dicts run as one independent loop; multi-key dicts inside one entry zip together; stacked entries cross-product (top entry = outermost / slowest loop).
+
+**Signature (inline):** `@pytest.mark.testerkit_sweeps([entries])` — one positional list of axis-group dicts. Single-axis is `[{"name": [values]}]`; cross-product is multiple entries; zipped paired values are multiple keys in one entry.
+
+```python
+# Single axis
+@pytest.mark.testerkit_sweeps([{"vin": [3.3, 5.0, 12.0]}])
+def test_rail(vin, psu, dmm, verify): ...
+
+# Cross-product — outer first, inner last
+@pytest.mark.testerkit_sweeps([
+    {"temperature": [-40, 25, 85]},  # outer
+    {"vin": [3.3, 5.0, 12.0]},        # inner
+])
+def test_rail_temp_sweep(temperature, vin, psu, dmm, verify): ...
+
+# Zipped axis — same-length lists, paired
+@pytest.mark.testerkit_sweeps([{"load_a": [0.1, 0.4], "load_b": [10, 20]}])
+def test_zipped(load_a, load_b, ...): ...
+```
+
+**Sidecar equivalent:**
+
+```yaml
+sweeps:
+  - {temperature: [-40, 25, 85]}
+  - {vin: [3.3, 5.0, 12.0]}
+```
+
+**`testerkit_sweeps` vs `@pytest.mark.parametrize`:** both work; both feed the same `inputs` lane on the vector row (query with `FieldRef.input(name)`). Use `testerkit_sweeps` when you want range expanders (`linspace`, `arange`, `logspace`, etc.) or sidecar parity; use `@pytest.mark.parametrize` when you want pytest's `pytest.param(..., id="...")` / `marks=[...]` per-row metadata. See [Test vectors & sweeps](../../how-to/execution/vector-expansion.md) for full semantics including range expanders and the `vectors` self-loop fixture.
+
+---
+
+## `testerkit_mocks`
+
+Install one or more mocks at test entry, unwound at teardown. Each entry has a `target:` and arbitrary `unittest.mock.patch.object` kwargs (`return_value`, `side_effect`, `wraps`, `spec`, etc.).
+
+**Signature:** `@pytest.mark.testerkit_mocks([entries])` where each entry is a `MockEntry` dict.
+
+```python
+@pytest.mark.testerkit_mocks([
+    {"target": "dmm.measure_dc_voltage", "return_value": 3.31},
+    {"target": "psu.measure_current", "side_effect": [0.1, 0.2, 0.3]},
+])
+def test_mocked(dmm, psu, verify): ...
+```
+
+**Sidecar equivalent:**
+
+```yaml
+mocks:
+  - {target: dmm.measure_dc_voltage, return_value: 3.31}
+  - {target: psu.measure_current, side_effect: [0.1, 0.2, 0.3]}
+```
+
+The target is `"<fixture>.<attr>"` — the pytest fixture name plus the attribute on the resolved fixture value. See [Mock mode](../../how-to/configuration/mock-mode.md) for the full priority resolution (per-test mocks > file-level mocks > station `mock_config` > zero).
+
+---
+
+## `testerkit_characteristics`
+
+Iterate the test body over a subset of the part spec's `characteristics`. Combined with `testerkit_connections` to select which signal-path connections to bind. Used by [spec-driven testing](../../how-to/execution/spec-driven-testing.md).
+
+**Signature:** `@pytest.mark.testerkit_characteristics([ids])` — list of characteristic IDs.
+
+```python
+@pytest.mark.testerkit_characteristics(["output_voltage", "output_current"])
+def test_rail(context, verify):
+    for char_id in context.characteristics:
+        verify(char_id, ...)
+```
+
+**Sidecar equivalent:**
+
+```yaml
+characteristics: [output_voltage, output_current]
+```
+
+---
+
+## `testerkit_connections`
+
+Select which fixture connections the test iterates over. Pairs with `testerkit_characteristics`. Two payload shapes:
+
+- **List of names** — bind by fixture-connection name: `@pytest.mark.testerkit_connections(["VOUT", "VIN"])`
+- **Dict mapping instrument → channels** — bind by instrument and channel selector: `@pytest.mark.testerkit_connections(dmm=["CH1", "CH2"])`
+
+**Sidecar equivalents:**
+
+```yaml
+connections: [VOUT, VIN]              # list form
+# OR
+connections: {dmm: [CH1, CH2]}        # dict form
+```
+
+The pytest plugin's `connections` fixture exposes the resolved `FixtureConnection` iterator for the test body.
+
+---
+
+## `testerkit_retry`
+
+Per-test retry policy. Translates to `pytest-rerunfailures`' `flaky` under the hood.
+
+**Signature:** `@pytest.mark.testerkit_retry(max_retries=, delay=, on=)`
+
+```python
+@pytest.mark.testerkit_retry(max_retries=2, delay=0.5, on=["AssertionError"])
+def test_flaky_settling(dmm, verify): ...
+```
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `max_retries` | `int >= 0` | `0` | 0 = single execution, 2 = up to 2 retries beyond original (3 total) |
+| `delay` | `float >= 0` | `0.0` | Seconds between attempts |
+| `on` | `list[str] \| None` | `None` (any) | Exception class names that trigger retry |
+
+**Sidecar equivalent:**
+
+```yaml
+retry: {max_retries: 2, delay: 0.5, on: [AssertionError]}
+```
+
+Each retry produces measurement rows with the same `vector_index` and an incremented `vector_retry`. See [Parquet schema → Retries](../data/parquet-schema.md#retries).
+
+---
+
+## `testerkit_prompts`
+
+Declare operator prompts the test can invoke via the `prompt` fixture. Keyword per prompt name.
+
+**Signature:** `@pytest.mark.testerkit_prompts(**by_name)` — each value matches `PromptConfig`.
+
+```python
+@pytest.mark.testerkit_prompts(
+    inspect={"message": "Verify LED is GREEN", "prompt_type": "confirm"},
+)
+def test_visual(prompt, verify):
+    prompt("inspect")  # blocks until operator responds
+    verify("led_state", read_led_color())
+```
+
+| Field | Type | Default | Meaning |
+|---|---|---|---|
+| `message` | `str` | (required) | Prompt text shown to the operator |
+| `prompt_type` | `"confirm" \| "choice" \| "input"` | `"confirm"` | What the operator UI shows |
+| `choices` | `list[str] \| None` | `None` | For `"choice"` type |
+| `timeout_seconds` | `int \| None` | `None` | Stop waiting after N seconds (returns a timed-out response) |
+
+**Sidecar equivalent:**
+
+```yaml
+prompts:
+  inspect: {message: "Verify LED is GREEN", prompt_type: confirm}
+```
+
+---
+
+## Composing `testerkit_characteristics` + `testerkit_connections`
+
+These two markers are the two halves of selecting which connections a test iterates over `ctx.connections` (the `connections` fixture): `testerkit_characteristics` says *which characteristic* on the part, and `testerkit_connections` says *which fixture connections* to bind. They're independent, so every combination of present / absent / by-name / by-channel / fixture-loaded / fixture-absent has a defined behavior. Find the row that matches your test.
+
+`testerkit_connections` takes one of two shapes (not both at once):
+
+- **`[name, ...]`** — bind by fixture-connection name. Requires a fixture YAML.
+- **`{instrument: [channels], ...}`** — bind by instrument → channel selector. Works without a fixture (synthesizes stubs) for early bringup.
+
+| Case | `testerkit_characteristics` | `testerkit_connections` | Fixture loaded? | Result |
+|------|---------------|----------------------|-----------------|--------|
+| 1 | — | — | any | No markers → `ctx.connections` is `None`; the test runs once with no connection context. |
+| 2 | `[X]` | — | yes | Iterate the fixture connections whose `uut_pin` (or `net`) matches a pin in `X`'s resolved pins. Order: characteristic order, then each characteristic's pin order (deduplicated). |
+| 3 | `[X]` | — | no | Empty iterator — no fixture means no connections to bind. The test iterates `ctx.connections` zero times. |
+| 4 | — | `[a, b]` (names) | yes | Iterate the named connections in the order listed. Unknown name → `pytest.UsageError`. |
+| 5 | — | `[a, b]` (names) | no | `pytest.UsageError` — connection names are only meaningful against a fixture YAML. |
+| 6 | — | `{inst: [ch]}` (channels) | yes | Match each `(instrument, channel)` against fixture connections, in listed order. No match → `pytest.UsageError`. `'all'` selects every connection on that instrument. |
+| 7 | — | `{inst: [ch]}` (channels) | no | Synthesize connection stubs (`name="{inst}_ch{ch}"`, no `uut_pin`) for early bringup. `'all'` → `pytest.UsageError` (nothing to enumerate). |
+| 8 | `[X]` | `[a, b]` (names) | yes | Resolve the names (case 4), then require every selected connection's `uut_pin` to fall in the union of the characteristics' pin sets. Out-of-set → `pytest.UsageError`. Listed order wins. |
+| 9 | `[X]` | `[a, b]` (names) | no | `pytest.UsageError` (case 5 — a fixture is required for connection names). |
+| 10 | `[X]` | `{inst: [ch]}` (channels) | yes | Resolve the channels (case 6), then require every match's `uut_pin` to fall in the union pin set. Out-of-set → `pytest.UsageError`. Listed order wins. |
+| 11 | `[X]` | `{inst: [ch]}` (channels) | no | `pytest.UsageError` — fixtureless channel stubs have no `uut_pin` to cross-check against the characteristics. Drop `testerkit_characteristics` for pure bringup, or load a fixture. |
+
+Invariants across the matrix:
+
+- **No part loaded, or an unknown characteristic ID** → `pytest.UsageError`.
+- **Iteration order** — when `testerkit_connections` is present it sets the order (user-listed); with characteristics alone, the order follows characteristic order then each characteristic's pin order.
+- **Declared but un-iterated** — if connections resolve to a non-empty set and the test body never iterates `ctx.connections`, the test fails with `AssertionError`. An empty resolved set (case 3) is not an error; the body just runs zero rounds.
+
+## Where markers live
+
+Same vocabulary, three delivery channels:
+
+| Channel | Example |
+|---|---|
+| Inline decorator | `@pytest.mark.testerkit_limits(output_voltage={"low": 3.135, "high": 3.465, "unit": "V"})` |
+| Sidecar YAML (`tests/test_<module>.yaml`) | `limits: { output_voltage: { low: 3.135, high: 3.465, unit: V } }` |
+| Profile YAML (`profiles/*.yaml`) | Same shape; applies session-wide via `--test-profile=<name>` |
+
+Resolution order (least → most specific): inline marker (class then method) → sidecar file-level → sidecar class/method → profile chain. Sidecar overrides inline because sidecar markers are applied after inline decorators and the resolver is last-wins. CLI flags (`-k`, `-m`, `--mock-instruments`, etc.) compose with this chain rather than overriding it wholesale. See [Test configuration](../configuration.md#sidecar-yaml) for the full merge semantics.
+
+## See also
+
+- [pytest-native reference](../overview/pytest-native.md) — how TesterKit tests use pytest's own collection / fixtures / markers
+- [TesterKit fixtures reference](fixtures.md) — all the fixtures the plugin exposes
+- [Models](../data/models.md) — `MeasurementLimitConfig`, `MockEntry`, `SweepEntry`, `RetryConfig`, `PromptConfig` field shapes
+- [Test vectors & sweeps](../../how-to/execution/vector-expansion.md) — `testerkit_sweeps` semantics + `vectors` self-loop fixture