testerkit 0.4.0__py3-none-any.whl

testerkit/_docs/tutorial/13-parallel-testing.md

@@ -0,0 +1,233 @@
+# Step 13: Parallel Testing
+
+**Goal:** Scale one bench from one UUT to two, tested at the same time, with zero changes to test code.
+
+## Prerequisites
+
+- [Step 7: Real Instruments](07-real-instruments.md) — station YAML, instrument channels
+- [Step 9: Production Ready](09-production.md) — fixture YAML, pin-to-instrument mapping, sidecar limits
+
+## The scenario
+
+One bench, two UUT positions, tested in parallel. Each position is a **site** — the same parallel-position concept STDF calls `SITE_NUM` and NI TestStand calls a "test socket." A fixture that declares two or more sites turns a bare `pytest` invocation into a parallel run: no `--fixture` flag, no test rewrite, no per-UUT script.
+
+A site's identity is its **0-based position in the fixture's `sites:` list** — `site_index`. It's never a field you set; it's just where the site sits in the list. `site_index 0` gets an optional `name:` label — a human-readable tag like `left` that has no bearing on execution order.
+
+## Growing a fixture to two sites
+
+A single-UUT fixture wires `connections:` directly. A multi-UUT fixture replaces that with `sites:` — an ordered list, one entry per UUT position, each with its own `connections:`:
+
+```yaml
+# fixtures/dual_site_bench.yaml
+id: dual_site_bench
+name: Dual-Site Bench Fixture
+description: >-
+  Two-UUT parallel fixture — left/right sites share the bench's psu
+  and dmm but land on different instrument channels.
+part_id: dual_rail_uut
+station_types: [bench]
+sites:
+  - name: left
+    connections:
+      vout:
+        name: vout
+        instrument: dmm
+        instrument_channel: "1"
+        instrument_terminal: hi
+        uut_pin: TP_VOUT
+        net: VOUT_3V3
+      vin:
+        name: vin
+        instrument: psu
+        instrument_channel: "1"
+        instrument_terminal: hi
+        uut_pin: TP_VIN
+        net: VIN_5V
+  - name: right
+    connections:
+      vout:
+        name: vout
+        instrument: dmm
+        instrument_channel: "2"
+        instrument_terminal: hi
+        uut_pin: TP_VOUT
+        net: VOUT_3V3
+      vin:
+        name: vin
+        instrument: psu
+        instrument_channel: "2"
+        instrument_terminal: hi
+        uut_pin: TP_VIN
+        net: VIN_5V
+```
+
+`left` is `site_index 0`, `right` is `site_index 1` — list position, not an authored field. Both sites route to the same instrument roles (`dmm`, `psu`) on the station, but each lands on its own `instrument_channel` — `left` on channel `"1"`, `right` on channel `"2"`. That's the whole trick: one physical DMM, one physical PSU, two UUT positions, no collision.
+
+Two or more sites makes this fixture **multi-site**, which is what fans a bare `pytest` invocation into parallel execution. One site is just the single-UUT case you already know — `connections:` directly on the fixture is shorthand for one unnamed site. For the full field-by-field schema, see [Fixture YAML reference](../reference/configuration.md#fixture-yaml); for the design rationale behind sites and shared instruments, see [Fixtures → Multi-UUT scaling](../concepts/configuration/fixtures.md#multi-uut-scaling-sites-shared-instruments-switching).
+
+## The station and the test don't change
+
+The station YAML declares `psu` and `dmm` exactly as a single-UUT bench would — it has no idea there are two sites:
+
+```yaml
+# stations/bench_dual.yaml
+id: bench_dual
+name: Dual-Site Bench
+station_type: bench
+instruments:
+  psu:
+    type: psu
+    driver: drivers.PSU
+    resource: TCPIP::192.168.1.101::INSTR
+    mock_config:
+      set_voltage: 5.0
+      set_current: 0.5
+      measure_voltage: 5.0
+      measure_current: 0.042
+  dmm:
+    type: dmm
+    driver: drivers.DMM
+    resource: TCPIP::192.168.1.102::INSTR
+    mock_config:
+      measure_dc_voltage: 3.3
+      measure_dc_current: 0.042
+```
+
+Neither does the test:
+
+```python
+# tests/test_dual_rail.py
+
+def test_vout_within_spec(verify, psu, dmm, context) -> None:
+    """5 V PSU input -> ~3.3 V DMM readback, on this site's connections."""
+    psu.set_voltage(5.0)
+    psu.set_current(0.5)
+    for _ in context.connections:
+        verify("vout", dmm.measure_dc_voltage())
+```
+
+```yaml
+# tests/test_dual_rail.yaml — sidecar
+tests:
+  test_vout_within_spec:
+    connections: [vout]
+    limits:
+      vout: {low: 3.2, high: 3.4, unit: V}
+```
+
+`context.connections` iterates the connections the sidecar's `connections: [vout]` list resolved for *this site* — see the [`connections` fixture reference](../reference/pytest/fixtures.md#connections-function). The test never names `left`, `right`, a channel, or an index; it just reads `dmm` and `psu` through its own site's wiring. The site-specific channel routing lives entirely in the fixture YAML from the previous section — that's what let the station and test files stay unmodified while the fixture grew from one site to two.
+
+## Launching a parallel run
+
+`pytest.ini` assigns a serial to each named site by default, so a bare `pytest` is already a complete parallel run:
+
+```ini
+# pytest.ini
+[pytest]
+addopts = --mock-instruments --uut-serials left=SN-A,right=SN-B
+```
+
+```cli
+cd examples/12-parallel-sites
+uv run pytest -q
+```
+
+```
+[site:0] .                                                                        [100%]
+[site:0] 1 passed in 0.43s
+[site:1] .                                                                        [100%]
+[site:1] 1 passed in 0.43s
+
+============================================================
+Multi-UUT Results
+============================================================
+  site[0]: PASS  1 passed in 0.43s
+  site[1]: PASS  1 passed in 0.43s
+============================================================
+```
+
+A fixture with 2+ sites is what triggers this: the parent process (the **orchestrator**) spawns one **worker** subprocess per site, each running the full test session against its own site's connections. `[site:N]` prefixes each worker's stdout as it streams back — the two lines interleave as the workers run concurrently, so `[site:1]` sometimes reports before `[site:0]`; the order isn't guaranteed. Below the per-site output, the `Multi-UUT Results` block is the orchestrator's own summary once both workers exit.
+
+You'll also see pytest print `no tests ran` from the orchestrator process itself — it collected zero tests directly (both workers did the real collecting), so this line is harmless.
+
+## Reading the result
+
+Two workers means two independent runs, each with its own serial:
+
+```cli
+uv run testerkit runs --limit 5
+```
+
+```
+Run ID     Started                    UUT Serial      Project              Station              Outcome
+----------------------------------------------------------------------------------------------------------
+437bdc0e   2026-07-01T18:00:00-0600   SN-B            parallel-sites-example bench_dual           passed
+7fa161df   2026-07-01T18:00:00-0600   SN-A            parallel-sites-example bench_dual           passed
+```
+
+Site 0 (`left`) ran as `SN-A`, site 1 (`right`) ran as `SN-B`. Each run's parquet carries the `site_index` / `site_name` it was frozen with at start — `SN-A` recorded `site_index=0, site_name="left"`, `SN-B` recorded `site_index=1, site_name="right"`. That freeze point matters: rename a site in the fixture YAML next month and this run's rows still read the name that was active when it ran. See [Multi-UUT testing → Parquet Data](../how-to/execution/multi-uut-testing.md#parquet-data) for the DuckDB query shape over those columns.
+
+Give it a few seconds before querying — ingest lands a beat after the summary prints. If `testerkit runs` comes back empty right after the run, re-run the command.
+
+## Experimenting with serial assignment
+
+`pytest.ini`'s `addopts` is a default, not a lock — any `--uut-serials` / `--site` / `--uut-serial` on the command line overrides it for that invocation.
+
+**Positional** — one serial per site, in fixture list order (`left` gets the first):
+
+```cli
+uv run pytest -q --uut-serials SN1,SN2
+```
+
+```
+[site:0] .                                                                        [100%]
+[site:0] 1 passed in 0.42s
+[site:1] .                                                                        [100%]
+[site:1] 1 passed in 0.42s
+
+============================================================
+Multi-UUT Results
+============================================================
+  site[0]: PASS  1 passed in 0.42s
+  site[1]: PASS  1 passed in 0.42s
+============================================================
+```
+
+**Indexed** (`site_index=serial`, any order) and **named** (`site_name=serial`) produce the same 2-worker run — only how the serial maps to a site differs:
+
+```cli
+uv run pytest -q --uut-serials 0=SN1,1=SN2
+uv run pytest -q --uut-serials left=SN1,right=SN2
+```
+
+**Single-lane** — target one site, single-process, no orchestrator:
+
+```cli
+uv run pytest -q --site left --uut-serial SN1
+```
+
+```
+.                                                                        [100%]
+1 passed in 0.43s
+```
+
+No `[site:N]` prefix, no `Multi-UUT Results` banner — this ran in the current process. It still records exactly as `left` would inside a parallel run (`site_index=0, site_name="left"`), which makes it the right tool for debugging one UUT position without waiting on its neighbor. `--site` always runs single-process, even against a multi-site fixture; pair it with `--uut-serial` (singular), not `--uut-serials`.
+
+## Why the shared instrument doesn't collide
+
+`psu` and `dmm` are one physical box each in this example, shared by both sites. TesterKit serializes calls to a shared instrument so `left` and `right` never talk to it at the same instant — you didn't write a lock anywhere in `test_dual_rail.py` for that to be true. Mock instruments are the one exception: under `--mock-instruments` each site gets its own mock state, so a fault injected on one site's `dmm` never leaks into the other's.
+
+For sync points, per-site environment variables, and debugging a hung or failing site, see [Multi-UUT testing](../how-to/execution/multi-uut-testing.md) — the full reference this chapter walked through.
+
+## You've completed the tutorial
+
+You've taken a suite from a bare `conftest.py` with one mock fixture through production traceability, live monitoring, and now parallel execution across multiple UUT positions on one bench. The full worked example for this step lives in [`examples/12-parallel-sites`](https://github.com/pragmatest-dev/testerkit/tree/main/examples/12-parallel-sites) — clone it, wipe its `data/` directory, and re-run any of the commands above against real output of your own.
+
+## Next Steps
+
+- [Multi-UUT testing](../how-to/execution/multi-uut-testing.md) — the full recipe: sync points, environment variables, debugging failures
+- [Fixtures → Multi-UUT scaling](../concepts/configuration/fixtures.md#multi-uut-scaling-sites-shared-instruments-switching) — the design behind sites, shared instruments, and switched routing
+- [Configuration reference](../reference/configuration.md#fixture-yaml) — fixture YAML field-by-field
+- [CLI reference](../reference/cli.md) — every `testerkit` command
+
+← [Step 12: Continuous Monitoring](12-continuous-monitoring.md)  |  [Tutorial index](index.md)

testerkit/_docs/tutorial/index.md

@@ -0,0 +1,61 @@
+# Tutorials
+
+Two independent ways to learn TesterKit — pick the one that fits how you want to start. They are not a sequence: the Quick Start is **not** "step 0" of the step-by-step path.
+
+## Quick Start
+
+`testerkit init quick_start --starter` scaffolds a complete project — part spec, station, fixture, a test, and config — that passes `pytest` immediately with mock instruments. Best when you want to see the whole thing working first, then read the walkthrough to understand each piece.
+
+```bash
+pip install testerkit
+testerkit init quick_start --starter && cd quick_start
+pytest
+```
+
+[Quick Start walkthrough →](quickstart.md)
+
+## Step-by-step tutorial
+
+Start from nothing — a bare `conftest.py` with one mock fixture — and add a single concept per step, up to a production-ready, fully traceable suite with live monitoring. Best when you want to learn each piece as you introduce it; each step builds on the previous one.
+
+| Step | Goal | What You'll Learn |
+|------|------|-------------------|
+| [1. First Test](01-first-test.md) | Run something | pytest, project structure |
+| [2. Running Without Hardware](02-mock-instruments.md) | Use mock mode | `--mock-instruments`, `mock_config` (station-config block of canned return values used when `--mock-instruments` is on) |
+| [3. pytest-native tests](03-fixtures.md) | Log measurements | the core per-test [TesterKit fixtures](../reference/overview/pytest-native.md) — `context` is the ambient run/UUT/station/vector state (always available; carries sweep params when present, observations always), `verify` records the measurement row AND raises on FAIL, `measure` records the row without raising (plus ~17 other public fixtures the plugin exposes — see [testerkit-fixtures](../reference/pytest/fixtures.md)) |
+| [4. Add Limits](04-limits.md) | Pass/fail criteria | [Limit](../reference/data/models.md), Measurement, [Outcome](../reference/data/models.md#enum-outcome) |
+| [5. Test Configuration](05-configuration.md) | Configure in YAML | [sidecar](05-configuration.md) (YAML next to a test file carrying vectors and limits) |
+| [6. Part Specifications](06-specifications.md) | Define [parts](../concepts/configuration/parts.md) | parts/*.yaml, [characteristics](../concepts/configuration/capabilities.md) |
+| [7. Real Instruments](07-real-instruments.md) | Talk to hardware | [stations/*.yaml](../concepts/configuration/stations.md), VISA, simulation |
+| [8. Capability Matching](08-capabilities.md) | Find compatible [stations](../concepts/configuration/stations.md) | [direction flip, matching API](../concepts/configuration/capabilities.md) |
+| [9. Production Ready](09-production.md) | Full [traceability](../how-to/execution/traceability.md) | [fixtures](../concepts/configuration/fixtures.md), test classes, sidecar |
+| [10. Live Monitoring](10-live-monitoring.md) | Monitor in real time | [sessions](../concepts/data/sessions.md), [events](../concepts/data/event-log.md), [channels](../concepts/data/data-stores.md) |
+| [11. Waveforms and Evidence](11-waveforms-and-evidence.md) | Capture a scope waveform and judge derived scalars | [three verbs](../concepts/data/three-verbs.md), `observe`, ChannelStore |
+| [12. Continuous Monitoring](12-continuous-monitoring.md) | Stream live DMM data from an interactive session into the operator UI | [three verbs](../concepts/data/three-verbs.md), `channels.stream`, interactive `connect` |
+| [13. Parallel Testing](13-parallel-testing.md) | Run one bench against two UUTs at once | multi-UUT [sites](../concepts/configuration/fixtures.md#multi-uut-scaling-sites-shared-instruments-switching), `site_index` / `site_name`, `--uut-serials`, the orchestrator/worker split |
+
+## Prerequisites
+
+- Python 3.11 or later
+- Basic familiarity with pytest
+- TesterKit installed (`pip install testerkit`)
+
+## Time Commitment
+
+Each step takes 10-15 minutes. You can complete the entire tutorial in about 2 hours, or work through it over several sessions.
+
+## What You'll Build
+
+By the end of this tutorial, you'll have:
+
+1. A working test suite for a voltage converter
+2. YAML-based configuration for limits and test parameters
+3. Tests that run with real instruments OR in simulation mode
+4. Automatic station matching based on required capabilities
+5. Full traceability from requirements to results
+6. Live monitoring of test sessions with event queries
+
+## Ready?
+
+- See it working now → [Quick Start](quickstart.md)
+- Learn it from the ground up → [Step 1: First Test](01-first-test.md)

testerkit/_docs/tutorial/quickstart.md

@@ -0,0 +1,282 @@
+# Quick Start
+
+Install TesterKit, scaffold a starter project, and run a passing test. Requires Python 3.11+.
+
+```bash
+# 1. Install TesterKit
+pip install testerkit
+
+# 2. Create a starter project
+testerkit init quick_start --starter
+cd quick_start
+
+# 3. Run the test
+pytest
+```
+
+The starter ships a single test (`test_output_voltage`). Run it and pytest reports `1 passed` — the measurement was taken against a mock instrument, checked against its limit, and recorded.
+
+> **Explore without hardware.** [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/pragmatest-dev/testerkit-starter) opens a browser sandbox to try TesterKit with no install — mock-instrument tests, the operator UI, analytics, and AI integration. Real instrument control (PyVISA/serial to a bench) needs a local install, so the sandbox stops there.
+
+> **Concepts cheat-sheet.** This quick start runs a complete TesterKit project, so it touches nearly every TesterKit concept at once — most for the first time. Each term below links forward to the tutorial step that introduces it properly:
+>
+> - **Part spec** — `parts/*.yaml`. Describes the device under test. → [Step 6](06-specifications.md), [concepts/parts](../concepts/configuration/parts.md)
+> - **Station YAML** — `stations/*.yaml`. Declares the bench's instruments. → [Step 7](07-real-instruments.md), [concepts/stations](../concepts/configuration/stations.md)
+> - **Sidecar YAML** — `tests/test_<module>.yaml`. Carries limits, sweeps, mocks for tests in that module. → [Step 5](05-configuration.md)
+> - **`verify` / `measure` / `context` fixtures** — three of the fixtures TesterKit contributes. → [Step 3](03-fixtures.md), [reference/testerkit-fixtures](../reference/pytest/fixtures.md)
+> - **`@pytest.mark.testerkit_limits`** — one of the seven TesterKit markers; pins a limit at the top of a test. → [Step 4](04-limits.md), [reference/testerkit-markers](../reference/pytest/markers.md)
+> - **`mock_config`** — Per-instrument return values for mock mode. → [Step 2](02-mock-instruments.md), [how-to/mock-mode](../how-to/configuration/mock-mode.md)
+> - **Characteristics, bands, accuracy, `when:`** — Part-spec vocabulary. → [Step 6](06-specifications.md), [reference/catalog-schema](../reference/catalog/schema.md)
+> - **Capability matching** — How TesterKit pairs a part to a station. → [Step 8](08-capabilities.md), [concepts/capabilities](../concepts/configuration/capabilities.md)
+> - **MCP** — Model Context Protocol; how AI agents drive TesterKit. → [how-to/mcp-integration](../how-to/overview/mcp-integration.md)
+
+## Project Structure
+
+TesterKit projects follow a standard folder structure. The UI is driven by these folders.
+
+```
+quick_start/
+├── testerkit.yaml                  # Project config (data_dir, default station, mock mode)
+├── parts/                       # WHAT you're testing
+│   └── example_part.yaml        # Part specification
+├── stations/                    # WHERE you test
+│   └── starter_station.yaml     # Instruments + addresses
+├── fixtures/                    # HOW parts are connected to instruments
+│   └── example_fixture.yaml     # Pin-to-channel mappings
+├── instruments/                 # Instrument asset records (identity, calibration)
+│   ├── psu.yaml
+│   └── dmm.yaml
+├── tests/                       # Test code + sidecar config
+│   ├── conftest.py              # Custom fixtures (optional — roles auto-register)
+│   ├── test_example.py          # Test functions
+│   └── test_example.yaml        # Sidecar (limits, sweeps, mocks)
+├── data/                        # Output (gitignored)
+└── pyproject.toml
+```
+
+## Understanding the Starter Project
+
+When you run `testerkit init quick_start --starter`, it generates all of these files. Here's what each one does:
+
+### Part Spec (`parts/example_part.yaml`)
+
+```yaml
+# parts/example_part.yaml
+id: "example_part"
+name: "Example Part"
+description: "Auto-generated example part specification"
+
+pins:
+  TP_VOUT: {name: "TP1", net: "VOUT_3V3", description: "Output voltage test point"}
+
+characteristics:
+  output_voltage:
+    function: "dc_voltage"
+    direction: "output"
+    unit: "V"
+    pin: "TP_VOUT"
+    bands:
+    - value: 3.3
+      accuracy: {pct_reading: 2.0}
+```
+
+### Station Config (`stations/starter_station.yaml`)
+
+```yaml
+# stations/starter_station.yaml
+id: "starter_station"
+name: "Starter Station"
+description: "Auto-generated starter station with mock instruments"
+
+instruments:
+  psu:
+    type: "psu"
+    resource: "TCPIP::192.168.1.100::INSTR"
+    mock: true  # Start with mocks, switch to real hardware later
+    mock_config: {set_voltage: null, enable_output: null, measure_voltage: 5.0, measure_current: 0.25}
+
+  dmm:
+    type: "dmm"
+    resource: "TCPIP::192.168.1.101::INSTR"
+    mock: true
+    mock_config: {measure_dc_voltage: 3.3}
+```
+
+For real hardware, just remove `mock: true`. TesterKit uses [PyVISA](https://pyvisa.readthedocs.io/) directly:
+
+```yaml
+# stations/bench_1.yaml - Real hardware
+id: bench_1
+name: "Test Bench 1"
+
+instruments:
+  dmm:
+    type: dmm
+    resource: "TCPIP::192.168.1.100::INSTR"
+    # No mock: true → uses PyVISA, fixture has .query()/.write()
+```
+
+Or use [PyMeasure](https://pymeasure.readthedocs.io/) for high-level drivers (100+ instruments):
+
+```yaml
+instruments:
+  dmm:
+    type: dmm
+    driver: pymeasure.instruments.keysight.Keysight34461A
+    resource: "TCPIP::192.168.1.100::INSTR"
+```
+
+### Test Code (`tests/test_example.py`)
+
+Tests are **plain pytest** — no decorator, no base class. TesterKit's pytest integration contributes [fixtures](../reference/pytest/fixtures.md) (the per-test `context` / `verify` / `measure`, plus `pins`, `instruments`, per-role auto-fixtures from the station YAML, etc.) and [seven markers](../reference/pytest/markers.md). For how TesterKit tests use pytest's own collection / fixture / marker mechanisms see [pytest-native reference](../reference/overview/pytest-native.md).
+
+```python
+# tests/test_example.py
+def test_output_voltage(context, psu, dmm, verify) -> None:
+    """Verify output voltage is within spec."""
+    vin = context.get_param("vin", 5.0)
+    psu.set_voltage(vin)
+    psu.enable_output()
+    # verify() resolves the limit from the sidecar / part YAML,
+    # records the measurement, and raises on fail.
+    verify("output_voltage", float(dmm.measure_dc_voltage()))
+```
+
+For measurements that don't come from the part spec, use `measure(name, value, limit={"low": ..., "high": ..., "unit": "V"})` with inline limits or a sidecar `test_<module>.yaml`.
+
+### Sidecar (`tests/test_example.yaml`)
+
+Sidecar YAML carries limits, sweeps, and mocks alongside the test file. A top-level key applies to every test in the module; per-test overrides go under `tests:`. The starter ships a per-test limit:
+
+```yaml
+# tests/test_example.yaml
+tests:
+  test_output_voltage:
+    limits:
+      output_voltage:
+        low: 3.234
+        high: 3.366
+        unit: V
+```
+
+Sweeps and mocks live here too — e.g. a module-level `sweeps: [{vin: [5.0]}]` to parametrize, or `mocks: [{target: dmm.measure_dc_voltage, return_value: 3.31}]` (the starter instead sets mock returns in the station's `mock_config`).
+
+### Running Tests
+
+The starter's `pyproject.toml` bakes the station, mock mode, and a UUT serial into `addopts` (and `testerkit.yaml` sets the same defaults), so the everyday command is just:
+
+```bash
+pytest
+```
+
+That expands to the explicit form below — useful when you want to override a default or run from outside the project:
+
+```bash
+# Mock-instrument run (the starter's default)
+pytest tests/ --station=starter_station --mock-instruments --uut-serial=STARTER001 -v
+
+# With real hardware (drop --mock-instruments; use a real serial)
+pytest tests/ --station=starter_station --uut-serial=SN001 -v
+```
+
+> **On `--uut-serial` for early articles:** if your first UUT doesn't have
+> a real serial yet (engineering build, breadboard, dev unit), call it
+> whatever you like — `bob`, `proto-1`, `dev`. The serial is just the
+> identifier the run record will be filed under. Best practice once you
+> have real units is to use the value that uniquely identifies what is
+> being tested and measured (printed serial, scanned barcode, lot+sequence).
+
+## The Pattern
+
+Every TesterKit test follows this pattern:
+
+1. **GET CONDITIONS** from `context.get_param(...)` (not hardcoded)
+2. **SET UP** stimulus (PSU voltage, load current)
+3. **MEASURE** the result
+4. **CHECK** with `verify(name, value)` or `measure(name, value, ...)` — never `assert 3.0 <= v <= 3.6`
+
+```python
+def test_something(context, psu, dmm, verify):
+    vin = context.get_param("vin", 5.0)     # GET from context
+    psu.set_voltage(vin)                    # SET UP
+    psu.enable_output()
+    verify("output_voltage",            # MEASURE + CHECK + RECORD
+               dmm.measure_dc_voltage())
+```
+
+**No hardcoded values in code.** Conditions come from `context` (populated by native `@pytest.mark.parametrize` or sidecar YAML). Limits come from the part spec, an inline `@pytest.mark.testerkit_limits` decorator, or the sidecar's `limits:` field — never inline asserts.
+
+For the full reference — markers, sidecar YAML, `context.changed()`, mocks, retries — see the [Writing Tests guide](../how-to/execution/writing-tests.md).
+
+## View Results
+
+### CLI
+
+```bash
+testerkit runs              # List recent runs
+testerkit show <run_id>     # Show run details
+```
+
+### Operator UI
+
+```bash
+testerkit serve
+# Open http://localhost:8000
+```
+
+### Programmatic
+
+Each run writes one parquet at `data/runs/{date}/*.parquet`. Measurements are
+nested under the vector rows (`record_type = 'vector'`), so read them with a
+DuckDB `UNNEST`:
+
+```python
+import duckdb
+
+rows = duckdb.sql("""
+    SELECT run_id, m.name, m.value, m.unit, m.outcome
+    FROM read_parquet('data/runs/**/*.parquet', union_by_name=true),
+         UNNEST(measurements) AS t(m)
+    WHERE record_type = 'vector'
+""").fetchall()
+for row in rows:
+    print(row)
+```
+
+For cross-run analytics (yield, Ppk, Pareto) use the higher-level
+[`MeasurementsQuery`](../reference/data/query-api.md) API instead of reading
+parquet directly.
+
+## Key Folders
+
+| Folder | Purpose | UI Page |
+|--------|---------|---------|
+| `parts/` | Part specs (what you're testing) | /parts |
+| `stations/` | Station configs (instruments + addresses) | /stations |
+| `fixtures/` | Pin-to-instrument mappings | /fixtures |
+| `instruments/` | Instrument asset records (identity, calibration) | /instruments |
+| `tests/` | Test code + sidecar config | - |
+| `data/` | Parquet + event log output (gitignored) | /runs |
+
+## Optional: Set Up AI Assistance
+
+If you use an AI coding tool, TesterKit can register its [MCP (Model Context Protocol)](../how-to/overview/mcp-integration.md) server and generate project instructions so your AI understands TesterKit:
+
+```bash
+testerkit setup claude-code       # Claude Code
+testerkit setup claude-desktop    # Claude Desktop
+testerkit setup copilot           # GitHub Copilot (VS Code + CLI)
+```
+
+## Next: Connect Real Hardware
+
+When you're ready to move from mocks to real instruments, see [Step 7: Real Instruments](07-real-instruments.md). It covers station configuration, `testerkit discover`, driver wiring, and common troubleshooting.
+
+## Next Steps
+
+You've seen the whole loop. From here:
+
+- **Learn it from the ground up** → the [step-by-step tutorial](index.md) builds a project from nothing, one concept at a time. It's a separate path from this complete-project quick start, not a continuation of it.
+- [Core Concepts](../concepts/) — Understand parts, stations, and capabilities
+- [Writing Tests](../how-to/execution/writing-tests.md) — Patterns and best practices
+- [Configuration Reference](../reference/configuration.md) — YAML schema details

testerkit/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""Built-in analysis: yield, capability, Pareto, trend, and test time metrics.
+
+Import directly from the submodule that owns the type:
+
+    from testerkit.analysis.measurements_query import MeasurementsQuery
+    from testerkit.analysis.runs_query import RunsQuery
+    from testerkit.analysis.steps_query import StepsQuery
+    from testerkit.analysis.metrics import calculate_ppk, pareto_analysis
+"""

testerkit/analysis/_common.py

@@ -0,0 +1,24 @@
+"""Shared utilities for the analysis module."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from testerkit.data.models import ensure_utc
+
+
+def parse_datetime(value: str | datetime | None) -> datetime | None:
+    """Parse a datetime string or pass through a datetime object.
+
+    Handles ISO format strings and the common "Z" UTC suffix. Returns a
+    UTC-aware datetime (naive inputs are assumed UTC, the server's storage
+    convention), or None on failure (malformed strings, None input).
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return ensure_utc(value)
+    try:
+        return ensure_utc(datetime.fromisoformat(value.replace("Z", "+00:00")))
+    except ValueError:
+        return None