Skip to content

Testing with Zelos SDK

The Zelos SDK includes a pytest-based framework for hardware-in-the-loop testing, system validation, and real-time data checks.

Quick Start

# Install
pip install zelos-sdk

# Run checks and see the checkerboard
pytest --log-cli-level=INFO

# Also stream every test's trace data to the Agent
pytest --zelos-trace --log-cli-level=INFO

# Stream + record to files (artifacts dir required)
pytest --zelos-trace --zelos-trace-file --zelos-local-artifacts-dir=./artifacts

Minimal test:

import zelos_sdk

motor = zelos_sdk.TraceSourceCache("motor")
motor.add_event("status", [
    zelos_sdk.TraceEventFieldMetadata("rpm", zelos_sdk.DataType.Float64),
    zelos_sdk.TraceEventFieldMetadata("current", zelos_sdk.DataType.Float64, "A"),
])

def test_reaches_target(check):
    motor.status.log(rpm=2000.0, current=12.0)  # your bench code logs these
    check.that(motor.status.rpm, ">", 1900,
               temporal="within_duration", duration_s=0.5)
    check.that(motor.status.current, "<", 50,
               temporal="for_duration", duration_s=2.0)

A test that requests check connects to the agent on its own. Checks on literals and TraceSourceCache fields, like these two, run without an agent.

What You Get

  • Checker: expressive, time-aware checks with visual “checkerboard” output
  • Recording: automatic .trz files per function/class/module/session
  • Logging: capture Python logs as trace events and stream to the Agent
  • Reports: auto-linked trace files in HTML reports (auto-configured when pytest-html is installed and an artifacts dir is set)

Notes:

  • Plugins are auto-registered; no pytest_plugins setup required
  • When recording, pass --zelos-local-artifacts-dir=./artifacts

How it works

  • Plugins auto-load via pytest11 entry point (pytest-zelos-plugins), so no pytest_plugins boilerplate.
  • Config plugin creates --zelos-local-artifacts-dir (if provided) and formats --zelos-artifact-basename, then triggers pytest_zelos_configure.

  • Trace plugin:

  • Streaming: --zelos-trace connects the SDK to the agent at --zelos-trace-url when the session starts, so every test streams its trace data.

  • Recording: --zelos-trace-file + scope fixtures write .trz files to the artifacts dir.
  • Logging: forward Python logs (--zelos-trace-logging) or print events to stdout (--zelos-trace-stdout with --zelos-log).
  • HTML links: adds .trz links to pytest-html reports when installed.
  • Report plugin: if pytest-html is installed, an artifacts dir is set and no --html is provided, auto-writes {artifact_basename}-report.html in the artifacts dir and enables self-contained HTML.
  • Agent plugin: provides the agent fixture. It connects to --zelos-agent-url (then ZELOS_AGENT_URL, then http://localhost:2300) on first use, and opens a per-test checkerboard.
  • Checker plugin: provides the check fixture (agent.check) for time-aware, readable assertions.

Configure

  • Minimal pytest.ini 
    [pytest]
addopts = --zelos-trace
          --log-cli-level=INFO
  • Recording (artifacts dir required): see Trace Recording
  • All options: see Configuration

Copy-paste pytest.ini (stream + record + logs)

[pytest]
addopts =
  -sv
  --zelos-trace
  --zelos-trace-url=grpc://localhost:2300
  --zelos-trace-file
  --zelos-trace-file-scope=function
  --zelos-local-artifacts-dir=./artifacts
  --zelos-trace-logging
  --zelos-trace-logging-level=info

log_cli = true
log_cli_level = INFO

Next Steps