Configuration Reference

All command-line options, configuration files, and environment variables.

Command-Line Options

Core Options

Option	Description	Default
--zelos-trace	Enable streaming to Agent	False
--zelos-trace-url URL	Agent URL	grpc://localhost:2300
--zelos-log	Enable SDK logging	False
--zelos-log-level LEVEL	SDK log level (trace/debug/info/warn/error)	info

Recording Options

Option	Description	Default
--zelos-trace-file	Record to .trz files	False
--zelos-trace-file-scope SCOPE	Recording scope (function/class/module/session)	function
--zelos-local-artifacts-dir DIR	Output directory for artifacts (required when recording)	None
--zelos-artifact-basename FORMAT	Artifact naming format (used as prefix)	{date:%Y%m%d-%H%M%S}-zelos

Logging Options

Option	Description	Default
--zelos-trace-logging	Capture Python logs to trace	False
--zelos-trace-logging-level LEVEL	Log capture level (debug/info/warning/error/critical)	info
--zelos-trace-logging-source-name NAME	Source name for logs	logger
--zelos-trace-stdout	Print trace events to console	False
--zelos-trace-stdout-level LEVEL	Console output level	info

Notes:

• Plugins are auto-registered via pytest11 entry point (pytest-zelos-plugins = "zelos_sdk.pytest.plugins"). You typically do not need to add pytest_plugins manually.
• --zelos-trace initializes the SDK with a gRPC client to the Agent using --zelos-trace-url. If you only want SDK logging without streaming, use --zelos-log without --zelos-trace.

Logging modes:

• SDK logging (--zelos-log, --zelos-log-level): enables internal SDK/native logs.
• Trace logging (--zelos-trace-logging, --zelos-trace-logging-level): forwards Python logging records as trace events.
• Stdout tracing (--zelos-trace-stdout, --zelos-trace-stdout-level): prints trace events; level accepts standard names (debug/info/warning/error/critical).

pytest.ini Configuration

Minimal Configuration

[pytest]
# Just streaming
addopts = --zelos-trace

# Enable checker output
log_cli = true
log_cli_level = INFO

Complete Example

[pytest]
# Zelos configuration
addopts =
    # Verbosity and output
    -sv
    --tb=short

    # Enable tracing
    --zelos-trace
    --zelos-trace-url=grpc://localhost:2300

    # Enable recording
    --zelos-trace-file
    --zelos-trace-file-scope=function
    --zelos-local-artifacts-dir=./test-artifacts

    # Artifact naming
    --zelos-artifact-basename={date:%Y%m%d-%H%M%S}-test

    # Enable logging capture
    --zelos-trace-logging
    --zelos-trace-logging-level=info

    # SDK logging
    --zelos-log
    --zelos-log-level=info

    # HTML report
    --html=test-artifacts/report.html
    --self-contained-html

# Console output for checker
log_cli = true
log_cli_level = INFO
log_cli_format = %(asctime)s [%(levelname)s] %(message)s

Combined Streaming + Recording + Log Forwarding (Minimal)

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

Notes

• The pytest plugins read options from the command line or addopts in configuration files. Environment variables are not used for pytest plugin configuration.
• To set the Agent URL for tracing, use --zelos-trace-url or pass it via zelos_sdk.init(client_config=TracePublishClientConfig(url=...)) in your own setup.
• When --zelos-trace-file is enabled, scope-specific fixtures (trace_file_*) are automatically activated; ensure --zelos-local-artifacts-dir is provided.

pyproject.toml Configuration

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]

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

log_cli = true
log_cli_level = "INFO"

markers = [
    "slow: marks tests as slow",
    "hardware: requires hardware",
]

Hooks Configuration

pytest_zelos_configure

# conftest.py
def pytest_zelos_configure(config):
    """Called after pytest configuration."""
    # Customize behavior as needed
    if getattr(config, "zelos_local_artifacts_dir", None):
        pass

pytest_zelos_trace_file_name

# conftest.py
def pytest_zelos_trace_file_name(request):
    """Customize trace file naming."""
    import hashlib

    # Include test ID in filename
    test_id = hashlib.md5(request.node.nodeid.encode()).hexdigest()[:8]
    return f"{request.node.name}_{test_id}"

Plugin Registration

Default (Auto-enabled)

# Automatically registered - no action needed
# All plugins are available

Explicit Registration

# conftest.py
pytest_plugins = [
    "zelos_sdk.pytest.plugins",  # All plugins
]

# Or individual plugins
pytest_plugins = [
    "zelos_sdk.pytest.checker",
    "zelos_sdk.pytest.trace",
    "zelos_sdk.pytest.config",
    "zelos_sdk.pytest.report",
]

Disable Plugins

# Disable all Zelos plugins
pytest -p no:pytest-zelos-plugins