Configuration Reference¶

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

Command-Line Options¶

Core Options¶

Option	Description	Default
`--zelos-trace`	Connect the SDK to the agent at session start, so every test streams its trace data	False
`--zelos-trace-url URL`	Agent URL for `--zelos-trace`	grpc://localhost:2300
`--zelos-agent-url URL`	Agent URL for the `agent` and `check` fixtures	`ZELOS_AGENT_URL`, then http://localhost:2300
`--zelos-log`	Enable SDK logging	False
`--zelos-log-level LEVEL`	SDK log level (trace/debug/info/warn/error/off). Applies only with `--zelos-log`.	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 trace files, check results and the HTML report. Required when recording.	None
`--zelos-artifact-basename FORMAT`	Prefix for trace files and the HTML report. `{date}` is the run's start time.	{date:%Y%m%d-%H%M%S}-zelos

Logging Options¶

Option	Description	Default
`--zelos-trace-logging`	Record Python `logging` records as trace events	False
`--zelos-trace-logging-level LEVEL`	Lowest level to record (debug/info/warning/error/critical)	info
`--zelos-trace-logging-source-name NAME`	Trace source name for the log events	logger
`--zelos-trace-stdout`	Print trace events to the console. Needs `--zelos-log`.	False
`--zelos-trace-stdout-level LEVEL`	Level the console lines are logged at (trace/debug/info/warn/error/off)	info

Which agent a test talks to¶

Two options name an agent, because two parts of the plugin connect to one:

--zelos-trace connects the trace publisher when the session starts. Every test then streams its trace data to --zelos-trace-url.
A test that requests check or agent connects on its own, to --zelos-agent-url. Its checks and queries go to that agent. If --zelos-trace is not set, the first such test also connects the trace publisher there, so trace data streams from then on.

The trace publisher connects once per session, and the first connection wins. When you set both options, point them at the same agent.

You do not need --zelos-trace to run checks. Use it when tests that never request check or agent must stream their data too.

Logging modes¶

SDK logging (--zelos-log, --zelos-log-level): enables the SDK's internal logs.
Trace logging (--zelos-trace-logging, --zelos-trace-logging-level): records Python logging records as log events on the source named by --zelos-trace-logging-source-name. The events stream and record like any other trace data.
Stdout tracing (--zelos-trace-stdout, --zelos-trace-stdout-level): prints each trace message through the SDK log. Set --zelos-log, or nothing prints. A line prints only when --zelos-trace-stdout-level is at or above --zelos-log-level.

pytest.ini Configuration¶

Minimal Configuration¶

[pytest]
# Stream every test's data to the agent
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

    # Stream to the agent
    --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 (needs pytest-html)
    --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

Notes¶

Only --zelos-agent-url reads an environment variable: ZELOS_AGENT_URL. Every other option comes from the command line or from addopts.
--zelos-trace-url always has a value, so --zelos-trace never reads ZELOS_AGENT_URL.
To connect the trace publisher from your own code, call zelos_sdk.init(url=...). TracePublishClientConfig carries batching settings only (batch_size, batch_timeout_ms).
--zelos-local-artifacts-dir resolves against pytest's rootdir. The plugin creates the directory if it is missing.
When --zelos-local-artifacts-dir is set, every test that requests check or agent writes {test_name}.checks.json there. A failed check then fails the test at the end, not at once. See Checks.
When --zelos-trace-file is set, the trace_file_* fixtures record automatically. Without --zelos-local-artifacts-dir, each test errors with RuntimeError: Local artifacts directory is not set.

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",
    "check_config: configure the zelos check fixtures for one test",
]

List check_config under markers if you run with --strict-markers, so pytest accepts the zelos marker.

Hooks Configuration¶

pytest_zelos_configure¶

Runs once, after the plugin has read its options. config.zelos_local_artifacts_dir is set when --zelos-local-artifacts-dir was given.

# 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¶

Return a file name without the .trz extension. Return None to keep the default 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)¶

Installing zelos-sdk registers the plugin through the pytest11 entry point pytest-zelos-plugins. It loads zelos_sdk.pytest.plugins, which brings every option, fixture and hook. Add nothing to conftest.py. With --strict-markers, also list the check_config marker under markers (see above).

Explicit Registration¶

Register the plugin yourself only when autoload is off: under PYTEST_DISABLE_PLUGIN_AUTOLOAD=1, or after -p no:pytest-zelos-plugins. Load the whole bundle by its module name, in one of two ways:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p zelos_sdk.pytest.plugins

# conftest.py in the rootdir
pytest_plugins = ["zelos_sdk.pytest.plugins"]

Warning

Do not register the plugin while autoload is on. pytest then loads it twice and stops with ValueError: Plugin already registered under a different name.

Do not register the subpackages one by one. check depends on the agent fixture, so zelos_sdk.pytest.checker alone fails with fixture 'agent' not found. zelos_sdk.pytest.plugins is the one supported entry.

Disable Plugins¶

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