ecu-tests/docs/01_run_sequence.md

Run Sequence: What Happens When You Start Tests

This document walks through the exact order of operations when you run the framework with pytest, what gets called, and where configuration/data is fetched from.

High-level flow

1. You run pytest from PowerShell
2. pytest reads pytest.ini and loads configured plugins (including our custom conftest_plugin)
3. Test discovery collects tests under tests/
4. Session fixtures run:
   • config() loads YAML configuration
   • lin() selects and connects the LIN interface (Mock, MUM, or the deprecated BabyLIN)
   • flash_ecu() optionally flashes the ECU (if enabled)
5. Tests execute using fixtures and call interface methods
6. Our plugin extracts test metadata (Title, Requirements, Steps) from docstrings
7. Reports are written to reports/report.html and reports/junit.xml

Detailed call sequence

sequenceDiagram
  autonumber
  participant U as User (PowerShell)
  participant P as pytest
  participant PI as pytest.ini
  participant PL as conftest_plugin.py
  participant T as Test Discovery (tests/*)
  participant F as Fixtures (conftest.py)
  participant C as Config Loader (ecu_framework/config.py)
  participant PS as Power Supply (optional)
  participant L as LIN Adapter (mock/MUM/BabyLIN)
  participant X as HexFlasher (optional)
  participant R as Reports (HTML/JUnit)

  U->>P: python -m pytest [args]
  P->>PI: Read addopts, markers, plugins
  P->>PL: Load custom plugin hooks
  P->>T: Collect tests
  P->>F: Init session fixtures
  F->>C: load_config(workspace_root)
  C-->>F: EcuTestConfig (merged dataclasses)
  F->>L: Create interface (mock, MUM, or BabyLIN SDK)
  L-->>F: Instance ready
  F->>L: connect()
  alt flash.enabled and hex_path provided
    F->>X: HexFlasher(lin).flash_hex(hex_path)
    X-->>F: Flash result (ok/fail)
  end
  opt power_supply.enabled and port provided
    Note over PS: owon_psu_quick_demo may open PSU via ecu_framework.power.owon_psu
  end
  loop for each test
    P->>PL: runtest_makereport(item, call)
    Note over PL: Parse docstring and attach metadata
    P->>L: send()/receive()/request()
    L-->>P: Frames or None (timeout)
  end
  P->>R: Write HTML (with metadata columns)
  P->>R: Write JUnit XML

PowerShell → python -m pytest
  ↓
pytest loads pytest.ini
  - addopts: --junitxml, --html, --self-contained-html, -p conftest_plugin
  - markers registered
  ↓
pytest collects tests in tests/
  ↓
Session fixture: config()
  → calls ecu_framework.config.load_config(workspace_root)
    → determines config file path by precedence
    → merges YAML + overrides into dataclasses (EcuTestConfig)
    → optionally merges config/owon_psu.yaml (or OWON_PSU_CONFIG) into power_supply
  ↓
Session fixture: lin(config)
  → chooses interface by config.interface.type
    - mock    → ecu_framework.lin.mock.MockBabyLinInterface(...)
    - mum     → ecu_framework.lin.mum.MumLinInterface(host, lin_device, power_device, ...)
    - babylin → ecu_framework.lin.babylin.BabyLinInterface(...)  [DEPRECATED]
  → lin.connect()
    - MUM connect() also powers up the ECU via power_out0 and waits boot_settle_seconds
  ↓
Optional session fixture: flash_ecu(config, lin)
  → if config.flash.enabled and hex_path set
  → ecu_framework.flashing.HexFlasher(lin).flash_hex(hex_path)
  ↓
Test functions execute
  → use the lin fixture to send/receive/request
  ↓
Reporting plugin (conftest_plugin.py)
  → pytest_runtest_makereport parses test docstring
  → attaches user_properties: title, requirements, steps, expected_result
  → pytest-html hooks add Title and Requirements columns
  ↓
Reports written
  → reports/report.html (HTML with metadata columns)
  → reports/junit.xml (JUnit XML for CI)

Where information is fetched from

• pytest configuration: pytest.ini
• YAML config (default): config/test_config.yaml
• YAML override via env var: ECU_TESTS_CONFIG
• BabyLIN SDK wrapper and SDF path (DEPRECATED): interface.sdf_path and interface.schedule_nr in YAML
• Test metadata: parsed from each test’s docstring
• Markers: declared in pytest.ini, attached in tests via @pytest.mark.*

Key components involved

• tests/conftest.py: defines config, lin, and flash_ecu fixtures
• ecu_framework/config.py: loads and merges configuration into dataclasses
• ecu_framework/lin/base.py: abstract LIN interface contract and frame shape
• ecu_framework/lin/mock.py: mock behavior for send/receive/request
• ecu_framework/lin/mum.py: MUM adapter (Melexis Universal Master via pylin + pymumclient)
• ecu_framework/lin/babylin.py: BabyLIN SDK wrapper adapter (DEPRECATED real hardware path via BabyLIN_library.py; emits DeprecationWarning on use)
• ecu_framework/flashing/hex_flasher.py: placeholder flashing logic
• conftest_plugin.py: report customization and metadata extraction

Edge cases and behavior

• If interface.type is babylin (deprecated) but the SDK wrapper or libraries cannot be loaded, hardware tests are skipped
• If interface.type is mum but pylin / pymumclient aren't importable, or interface.host is unset, hardware tests are skipped with a clear message
• If flash.enabled is true but hex_path is missing, flashing fixture skips
• Timeouts are honored in receive() and request() implementations
• Invalid frame IDs (outside 0x00–0x3F) or data > 8 bytes will raise in LinFrame
• MUM receive() is master-driven: it requires a frame ID; receive(id=None) raises NotImplementedError. Diagnostic frames needing LIN 1.x Classic checksum should use MumLinInterface.send_raw().