Hosam-Eldin Mostafa afd9da8206 docs: hardware test infrastructure, session-managed PSU, settle-then-validate

Documents the new layers introduced over the past several commits.

- docs/19_frame_io_and_alm_helpers.md (new): full reference for the
  FrameIO and AlmTester helpers — three access levels (high/mid/low),
  full API tables, fixture wiring, cookbook patterns, and §7
  describing the four-phase SETUP/PROCEDURE/ASSERT/TEARDOWN test
  pattern with the three template flavors plus a §7.4 link to the
  PSU+LIN template.

- docs/14_power_supply.md: rewritten and expanded.
    §3 cross-platform port resolution (Windows / WSL1 / WSL2 +
       usbipd-win / Linux native compatibility table)
    §4 auto-detection via idn_substr
    §5 session-managed power: contract for tests, must-not list,
       what changed in the existing tests
    §6 the settle-then-validate pattern: two-delays table (PSU
       bench-dependent vs ECU firmware-dependent), copy-paste
       example, tuning guidance for ECU_VALIDATION_TIME_S
    §6 PSU settling characterization (-m psu_settling)
    §7 library API reference table + safe_off_on_close
    §9 troubleshooting expanded with WSL2 usbipd-win + dialout

- docs/18_test_catalog.md: voltage-tolerance section refreshed for
  the settle-then-validate shape, new "Hardware – PSU settling
  (opt-in)" category, new §8 "Hardware-test infrastructure"
  documenting conftest.py, frame_io.py, alm_helpers.py,
  psu_helpers.py, and both templates.

- docs/05_architecture_overview.md: components list split into
  framework core / hardware test layer / artifacts. Mermaid diagram
  gained a Hardware-test helpers subgraph showing FrameIO,
  AlmTester, rgb_to_pwm, and the templates. Data/control flow
  summary describes the session-managed PSU and the helper layer.

- docs/15_report_properties_cheatsheet.md: PSU section split into
  per-test (function-scoped rp) and module-scoped (testsuite
  property) blocks; added psu_resolved_port, psu_resolved_idn,
  psu_settled_s, validation_time_s.

- docs/README.md: links to the new doc 19.

- README.md, TESTING_FRAMEWORK_GUIDE.md: project-structure trees
  expanded to show the full current layout — every file and
  directory under tests/hardware/ (conftest, helpers, templates,
  tests), tests/unit/, config/, docs/, scripts/, and vendor/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-08 19:02:42 +02:00

2.2 KiB

Raw Blame History

Report properties cheatsheet (record_property / rp)

Use these standardized keys when calling record_property("key", value) or the rp("key", value) helper. This keeps reports consistent and easy to scan across suites.

General

test_phase: setup | call | teardown (if you want to distinguish)
environment: local | ci | lab
config_source: defaults | file | env | env+overrides (already used in unit tests)

LIN (common)

lin_type: mock | mum | babylin (babylin is deprecated)
tx_id: hex string or int (e.g., "0x12")
tx_data: list of ints (bytes)
rx_present: bool
rx_id: hex string or int
rx_data: list of ints
timeout_s: float seconds

BabyLIN specifics (DEPRECATED)

sdf_path: string
schedule_nr: int
receive_result: frame | timeout
wrapper: mock_bl | _MockBytesOnly | real (for future)

Mock-specific

expected_data: list of ints

Power supply (PSU)

Per-test (function-scoped rp):

psu_idn: string from *IDN?
output_status_before: string ('ON'/'OFF'/'1'/'0'; raw output? response)
output_status_after: string (same, after the test toggled output)
set_voltage: float (V)
set_current: float (A)
measured_voltage: float | None (V) — parsed via measure_voltage_v()
measured_current: float | None (A) — parsed via measure_current_a()

Module-scoped (testsuite property — emitted once per file by the psu fixture):

psu_resolved_port: string — the port resolve_port actually opened (e.g. 'COM7', '/dev/ttyS6', '/dev/ttyUSB0')
psu_resolved_idn: string — the IDN response captured during resolution

Flashing

hex_path: string
sent_count: int (frames sent by stub/mock)
flash_result: ok | fail (for future real flashing)

Configuration highlights

interface_type: mock | mum | babylin (babylin is deprecated)
interface_channel: int
flash_enabled: bool

Tips

Prefer simple, lowercase snake_case keys
Use lists for byte arrays so they render clearly in JSON and HTML
Log both expected and actual when asserting patterns (e.g., deterministic responses)
Keep units in the key name when helpful (voltage/current include V/A in the name)

2.2 KiB Raw Blame History