Registry /
testing / opentelemetry-test-utils
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.000s · 26MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OTELTestBase
✓ from opentelemetry.test_utils import OTELTestBase
✗ from opentelemetry.test_utils import OTELTestBase
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.
import unittest
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, InMemorySpanExporter
from opentelemetry.test_utils import OTELTestBase
class MyInstrumentationTest(OTELTestBase):
def setUp(self):
super().setUp()
# Configure a tracer provider with an in-memory exporter for testing
self.exporter = InMemorySpanExporter()
self.span_processor = SimpleSpanProcessor(self.exporter)
self.tracer_provider = TracerProvider(resource=Resource.create({"service.name": "test-service"}))
self.tracer_provider.add_span_processor(self.span_processor)
trace.set_tracer_provider(self.tracer_provider)
self.tracer = trace.get_tracer(__name__)
def tearDown(self):
trace.set_tracer_provider(TracerProvider()) # Reset to default NoOpTracerProvider
self.span_processor.shutdown()
super().tearDown()
def test_basic_span_creation(self):
with self.tracer.start_as_current_span("test-span") as span:
span.set_attribute("key", "value")
span.add_event("my-event")
# Assert that one span was exported
spans = self.exporter.get_finished_spans()
self.assertEqual(len(spans), 1)
# Assert properties of the exported span
exported_span = spans[0]
self.assertEqual(exported_span.name, "test-span")
self.assertEqual(exported_span.attributes["key"], "value")
self.assertEqual(len(exported_span.events), 1)
self.assertEqual(exported_span.events[0].name, "my-event")
if __name__ == '__main__':
unittest.main()
Debug
Known issues
gotchaThe `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.fixAlways check release notes for compatibility when upgrading `opentelemetry-sdk` and `opentelemetry-test-utils`.
affects: All 0.x.x.bY versions
gotchaThis 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.fixConsider `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.
affects: All versions
breakingIn `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.fixReview tests that explicitly or implicitly interact with `NoOpTracer` behavior to ensure they handle proper span context propagation, even when no active SDK is present.
affects: >=0.61b0
deprecatedAs 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.fixMigrate logging instrumentation tests to use `opentelemetry-instrumentation-logging` instead of `opentelemetry-sdk.LoggingHandler`.
affects: >=0.61b0
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API for defining telemetry contracts.
opentelemetry-sdkrequiredOpenTelemetry SDK for processing and exporting telemetry, on which test utilities rely.