{"id":3203,"library":"opentelemetry-test-utils","title":"OpenTelemetry Test Utilities","description":"The `opentelemetry-test-utils` library provides common utilities and base classes designed to simplify unit testing of OpenTelemetry Python components. This includes helpers for capturing and asserting telemetry data (traces, metrics, logs) within a test environment. It is part of the larger OpenTelemetry Python project, currently at version 0.62b0, with new beta releases typically accompanying major `opentelemetry-python` releases.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python/tree/main/test_utils","tags":["opentelemetry","observability","testing","metrics","traces","logs","unittest"],"install":[{"cmd":"pip install opentelemetry-test-utils","lang":"bash","label":"Install stable version"},{"cmd":"pip install opentelemetry-test-utils==0.62b0","lang":"bash","label":"Install specific beta version"}],"dependencies":[{"reason":"Core OpenTelemetry API for defining telemetry contracts.","package":"opentelemetry-api"},{"reason":"OpenTelemetry SDK for processing and exporting telemetry, on which test utilities rely.","package":"opentelemetry-sdk"}],"imports":[{"note":"The `OTELTestBase` class was moved to `opentelemetry.test_utils` in recent versions from an SDK internal path.","wrong":"from opentelemetry.sdk.testing.util import OTELTestBase","symbol":"OTELTestBase","correct":"from opentelemetry.test_utils import OTELTestBase"},{"note":"While `opentelemetry-test-utils` is the package, some helper functions for testing, like `get_finished_spans`, reside directly within the `opentelemetry.sdk.testing.helpers` module.","symbol":"get_finished_spans","correct":"from opentelemetry.sdk.testing.helpers import get_finished_spans"}],"quickstart":{"code":"import unittest\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor, InMemorySpanExporter\nfrom opentelemetry.test_utils import OTELTestBase\n\nclass MyInstrumentationTest(OTELTestBase):\n    def setUp(self):\n        super().setUp()\n        # Configure a tracer provider with an in-memory exporter for testing\n        self.exporter = InMemorySpanExporter()\n        self.span_processor = SimpleSpanProcessor(self.exporter)\n        self.tracer_provider = TracerProvider(resource=Resource.create({\"service.name\": \"test-service\"}))\n        self.tracer_provider.add_span_processor(self.span_processor)\n        trace.set_tracer_provider(self.tracer_provider)\n        self.tracer = trace.get_tracer(__name__)\n\n    def tearDown(self):\n        trace.set_tracer_provider(TracerProvider()) # Reset to default NoOpTracerProvider\n        self.span_processor.shutdown()\n        super().tearDown()\n\n    def test_basic_span_creation(self):\n        with self.tracer.start_as_current_span(\"test-span\") as span:\n            span.set_attribute(\"key\", \"value\")\n            span.add_event(\"my-event\")\n\n        # Assert that one span was exported\n        spans = self.exporter.get_finished_spans()\n        self.assertEqual(len(spans), 1)\n\n        # Assert properties of the exported span\n        exported_span = spans[0]\n        self.assertEqual(exported_span.name, \"test-span\")\n        self.assertEqual(exported_span.attributes[\"key\"], \"value\")\n        self.assertEqual(len(exported_span.events), 1)\n        self.assertEqual(exported_span.events[0].name, \"my-event\")\n\nif __name__ == '__main__':\n    unittest.main()","lang":"python","description":"This quickstart demonstrates how to use `OTELTestBase` to set up an OpenTelemetry `TracerProvider` with an `InMemorySpanExporter` for testing. It includes a basic test case that creates a span, adds attributes and events, and then asserts the properties of the captured span. `OTELTestBase` handles much of the boilerplate for test cleanup."},"warnings":[{"fix":"Always check release notes for compatibility when upgrading `opentelemetry-sdk` and `opentelemetry-test-utils`.","message":"The `opentelemetry-test-utils` library often has a `0.x.x.bY` versioning scheme (e.g., 0.62b0) that is distinct from the main `opentelemetry-python` package's `1.x.x` version. Ensure you are installing the correct beta version that aligns with your `opentelemetry-sdk` version, as APIs can change rapidly in beta releases.","severity":"gotcha","affected_versions":"All 0.x.x.bY versions"},{"fix":"Consider `InMemorySpanExporter` from the SDK for basic assertion of traces/metrics in application tests. Use `opentelemetry-test-utils` when you need more comprehensive testing utilities or are developing OpenTelemetry components.","message":"This library is primarily intended for internal testing of OpenTelemetry components or custom instrumentations. For simpler application-level testing of whether spans are being generated, it might be sufficient to use `InMemorySpanExporter` directly from `opentelemetry.sdk.trace.export` without `opentelemetry-test-utils`, which might offer a more stable API.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review tests that explicitly or implicitly interact with `NoOpTracer` behavior to ensure they handle proper span context propagation, even when no active SDK is present.","message":"In `opentelemetry-python` v1.40.0 (corresponding to `opentelemetry-test-utils` 0.61b0), the behavior of `start_span` and `start_as_current_span` in `NoOpTracer` was fixed to propagate span contexts even without an SDK installed. Tests that relied on `NoOpTracer` *always* returning an `INVALID_SPAN` regardless of context might be affected.","severity":"breaking","affected_versions":">=0.61b0"},{"fix":"Migrate logging instrumentation tests to use `opentelemetry-instrumentation-logging` instead of `opentelemetry-sdk.LoggingHandler`.","message":"As of `opentelemetry-python` v1.40.0 (corresponding to `opentelemetry-test-utils` 0.61b0), `opentelemetry-sdk`'s `LoggingHandler` has been deprecated. Any test setups that rely on directly configuring `LoggingHandler` should migrate.","severity":"deprecated","affected_versions":">=0.61b0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}