Registry / testing / opentelemetry-test-utils

opentelemetry-test-utils

JSON →
library0.65b0pypypi✓ verified 23d ago

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.

pip install opentelemetry-test-utils
INSTALL
IMPORT
SIG · OPENTELEMETRY-TEST
O
opentelemetry-test-utils
testingpythonv0.65b0
Install
2.4s avg
Import
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.5MB
glibc
py 3.103.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.
fix
Always 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.
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.
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.
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.
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.
fix
Migrate 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.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
2
Resources
opentelemetry-test-utils — pip install opentelemetry-test-utils · libregistry