Trace Plugin¶

Use the Trace plugin to stream and/or record test execution data.

The Trace plugin provides test execution tracing capabilities for the Zelos Test Framework, allowing you to record and analyze test execution data.

Features¶

Trace forwarding to a remote Agent
Local trace file recording
Configurable trace scopes (session, module, class, function)
Customizable logging options

Installation¶

The Trace plugin comes pre-installed with the zeloscloud python package. To use it, add it to the pytest_plugins list in your conftest.py file:

# You may already have other plugins listed here
pytest_plugins = [
    # Add the trace plugin
    "zeloscloud.pytest.trace",
]

Command Line Options¶

The Trace plugin provides several command line options to control its behavior:

Option	Description
`--zelos-trace`	Enable tracing to the Zelos Agent
`--zelos-trace-url`	Set the Zelos Agent URL (default: predefined URL)
`--zelos-trace-file`	Enable tracing to a local file
`--zelos-trace-file-scope`	Set the scope for trace file recording (session, module, class, or function)
`--zelos-trace-log`	Enable log messages of the trace file writer
`--zelos-trace-log-level`	Set the log level for the trace file writer (trace, debug, info, warn, error)

Usage Examples¶

Basic Tracing¶

To enable tracing to the default Zelos Agent:

pytest --zelos-trace

Trace Forwarding to remote Agent¶

To specify a remote Agent to forward logs to:

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

File Tracing¶

To enable tracing to local files:

pytest --zelos-trace-file

Configuring Trace Scope¶

Control the granularity of trace files by setting the scope:

# One trace file per test function (default)
pytest --zelos-trace-file --zelos-trace-file-scope=function

# One trace file per test class
pytest --zelos-trace-file --zelos-trace-file-scope=class

# One trace file per module
pytest --zelos-trace-file --zelos-trace-file-scope=module

# One trace file for the entire session (default)
pytest --zelos-trace-file --zelos-trace-file-scope=session

Enabling Trace Logging¶

For debugging purposes, you can enable logging of the SDK:

pytest --zelos-trace-file --zelos-trace-log --zelos-trace-log-level=debug

Trace File Output¶

When using file tracing, trace files are saved to the local artifacts directory with the naming convention:

{artifact_basename}-trace-{nodeid}.trz

Where:

artifact_basename is the base name for artifacts (derived from local_artifacts_dir)
nodeid is derived from the pytest nodeid, sanitized for use in filenames
.trz is the trace file extension

Customizing Trace File Names¶

You can customize the trace file naming by implementing the pytest_zelos_trace_file_name hook in your conftest.py file:

def pytest_zelos_trace_file_name(request):
    """
    Customize the trace file name.

    :param request: The pytest request object
    :return: The custom file name (without extension) to use for the trace file
    """
    # Example: Use a git commit hash in the filename
    import subprocess
    commit_hash = subprocess.check_output(['git', 'rev-parse', 'HEAD']).decode('utf-8').strip()
    return f"custom-trace-{commit_hash}"

If this hook is not implemented, the default naming convention will be used.

Requirements¶

The native Zelos SDK (zelos_sdk) must be available for file tracing
A local artifacts directory must be configured for file tracing

API Reference¶

See zeloscloud.pytest.trace in the API Reference.