Pytest OpenTelemetry Plugin

Warnings

• gotcha pytest-opentelemetry itself only instruments; it requires the OpenTelemetry SDK and at least one exporter (e.g., `opentelemetry-exporter-otlp`) to be installed and configured to actually send traces. Without an exporter, spans will be collected in memory but not sent anywhere.
  Fix: Ensure you `pip install opentelemetry-sdk opentelemetry-exporter-otlp` (or another desired exporter) alongside `pytest-opentelemetry`. Configure the exporter endpoint and protocol using standard OpenTelemetry environment variables (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`) or CLI flags.
• gotcha Configuration can be done via standard OpenTelemetry environment variables (e.g., `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`) or specific `pytest` CLI flags (e.g., `--otel-service-name`, `--otel-endpoint`). Command-line arguments always take precedence over environment variables, which can lead to unexpected behavior if both are set conflictingly.
  Fix: Standardize your configuration method. If using environment variables, ensure no conflicting CLI flags are used. If using CLI flags, verify they are correctly applied and override any environment variables as intended.
• breaking The OpenTelemetry Python SDK, which `pytest-opentelemetry` relies upon, frequently introduces breaking changes or deprecations, especially for experimental features or during its stabilization phase for metrics and logs. Upgrading the underlying `opentelemetry-sdk` or related `opentelemetry-exporter-*` packages might introduce incompatibilities.
  Fix: Always review the OpenTelemetry Python SDK changelogs when updating `opentelemetry-sdk` or related packages. Pin your `opentelemetry-*` package versions in your `requirements.txt` to ensure consistent behavior.
• gotcha The plugin has a dependency on `pytest>=7.x`. Using it with older versions of `pytest` may result in unexpected behavior or errors.
  Fix: Ensure your project's `pytest` version is 7.0 or newer. Upgrade `pytest` if necessary: `pip install --upgrade pytest`.
• gotcha The `pytest-opentelemetry` README (as of version 1.x) states that it defaults to OTLP over gRPC for trace export. If your OpenTelemetry Collector or backend expects HTTP/protobuf, you must explicitly configure the `OTEL_EXPORTER_OTLP_PROTOCOL` environment variable.
  Fix: Set `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` if your collector expects HTTP. Also ensure the corresponding exporter package is installed (e.g., `opentelemetry-exporter-otlp-proto-http`).

Install

• pip install pytest-opentelemetry opentelemetry-sdk opentelemetry-exporter-otlp Install with OTLP exporter

Imports

• pytest-opentelemetry

  This is a pytest plugin and automatically registers upon installation. No direct Python imports are typically needed in your test files or conftest.py to enable its core functionality.

  Interaction is primarily via pytest CLI flags or OpenTelemetry environment variables.

Quickstart

To quickly get started, install the plugin along with the OpenTelemetry SDK and an OTLP exporter. Create a simple test file. The plugin registers automatically. To activate tracing and export spans, run `pytest` with the `--export-traces` flag. By default, it attempts to export to an OpenTelemetry Collector at `http://localhost:4317` using OTLP gRPC. For a basic demonstration without a collector, configure the `OTEL_TRACES_EXPORTER` environment variable to `console`.

import pytest
import os

# A simple test file (e.g., test_example.py)

def test_success():
    assert True

def test_failure():
    assert False

@pytest.mark.skip(reason="demonstrating skip")
def test_skipped():
    assert True

# To run and see console output:
# Set environment variables for console exporter for demonstration
# In a real scenario, you'd point to an OpenTelemetry Collector
# os.environ['OTEL_TRACES_EXPORTER'] = 'console'
# os.environ['OTEL_SERVICE_NAME'] = 'my-pytest-suite'

# Then run from your terminal:
# pytest --export-traces test_example.py -s -v