Zelos Plugins for pytest¶

The Zelos SDK provides a collection of pytest plugins that augment your test suite with tracing, reporting, configuration management, and assertion capabilities.

Quick Start¶

Simply pass --zelos-trace to pytest to start streaming your data live to your Zelos Agent.

pytest --zelos-trace

Stream and Record Data¶

To simultaneously stream and record traces for offline viewing:

pytest -sv --zelos-trace --zelos-local-artifacts-dir=./artifacts --zelos-trace-file

Alternatively, configure the plugins from your pytest.ini file:

[pytest]
addopts = -sv
          --zelos-trace
          --zelos-local-artifacts-dir=./artifacts
          --zelos-trace-file

Example Usage¶

Basic Test with Tracing and Checking¶

Run the below test with:

pytest -k test_motor_control --zelos-trace

import zelos_sdk

def test_motor_control(check):
    """Test motor control with tracing and assertions"""

    # Initialize trace source
    source = zelos_sdk.TraceSourceCacheLast("motor_test")
    source.add_event("motor_stats", [
        zelos_sdk.TraceEventFieldMetadata("rpm", zelos_sdk.DataType.Float64),
        zelos_sdk.TraceEventFieldMetadata("torque", zelos_sdk.DataType.Float64, "Nm"),
        zelos_sdk.TraceEventFieldMetadata("temperature", zelos_sdk.DataType.Float64, "celsius")
    ])

    # Log initial state
    source.motor_stats.log(rpm=0.0, torque=0.0, temperature=20.0)

    # Use checker for assertions
    check.that(source.motor_stats.rpm, "==", 0.0)
    check.that(source.motor_stats.temperature, "<", 25.0)

    # Simulate motor startup
    source.motor_stats.log(rpm=1500.0, torque=15.5, temperature=35.0)

    # Verify running state
    check.that(source.motor_stats.rpm, ">", 1000.0)
    check.that(source.motor_stats.torque, "between", 10.0, 20.0)

Plugins¶

Core Plugins¶

Plugin	Description	Documentation
Trace	Provides test execution tracing capabilities with local file recording and remote forwarding	Trace Plugin
Checker	Enhanced assertion framework with descriptive operators and time-based checks	Checker Plugin
Config	Manages common configuration for Zelos plugins, including artifact directories and naming	Config Plugin
Report	Automatic HTML test report generation with self-contained output	Report Plugin

Disable default plugin¶

To disable the default plugin, pass -p no:pytest-zelos-plugins on the command line.

pytest -p no:pytest-zelos-plugins

Manually Enable Plugins¶

To manually enable the plugins, add them to your conftest.py file:

pytest_plugins = [
    "zelos_sdk.pytest.plugins",
]

This single import automatically registers all available Zelos SDK plugins.

Alternatively, you can register individual plugins for more granular control:

pytest_plugins = [
    "zelos_sdk.pytest.config",    # Configuration management
    "zelos_sdk.pytest.trace",     # Trace recording and forwarding
    "zelos_sdk.pytest.checker",   # Enhanced assertions
    "zelos_sdk.pytest.report",    # HTML report generation
]

Configuration¶

Basic Config Options¶

See Config Plugin for more detailed options

--zelos-local-artifacts-dir DIR    # Local artifacts output directory
--zelos-artifact-basename FORMAT   # Artifact basename format (default: {date:%Y%m%d-%H%M%S}-zelos)

Basic Trace Options¶

See Trace Plugin for more detailed options

--zelos-trace                     # Enable tracing to Zelos Agent
--zelos-trace-file                # Enable tracing to local files

Example Configurations¶

Recording trace files per each test class¶

pytest --zelos-trace-file \
       --zelos-trace-file-scope=class \
       --zelos-local-artifacts-dir=./artifacts \
       tests/

Forward trace data to a remote agent¶

pytest --zelos-trace \
       --zelos-trace-url="grpc://192.168.1.100:2300" \
       tests/

Enable SDK Debug Logs¶

pytest --zelos-trace-log \
       --zelos-trace-log-level=debug \
       tests/

Custom Hooks¶

The plugins define custom pytest hooks for coordination:

def pytest_zelos_configure(config):
    """Called after pytest configuration to set up Zelos-specific settings"""
    pass

def pytest_zelos_trace_file_name(config, scope, item):
    """Called to determine trace file names based on scope and test item"""
    pass