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¶

HTTP trace forwarding to a remote server
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 HTTP server
`--zelos-trace-url`	Set the HTTP tracer 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-file-log`	Enable log messages of the trace file writer
`--zelos-trace-file-log-level`	Set the log level for the trace file writer (trace, debug, info, warn, error)

Usage Examples¶

Basic HTTP Tracing¶

To enable HTTP tracing to the default Zelos server:

pytest --zelos-trace

Custom HTTP Tracing¶

To specify a custom HTTP server for trace forwarding:

pytest --zelos-trace --zelos-trace-url="http://192.168.1.100:3200/write"

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
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 trace file writer:

pytest --zelos-trace-file --zelos-trace-file-log --zelos-trace-file-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 library (zeloscloud._native) 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.