or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdexporters.mdindex.mdjunit-integration.mdtest-builders.mdutilities.md
tile.json

tessl/maven-io-opentelemetry--opentelemetry-sdk-testing

OpenTelemetry SDK Testing utilities providing comprehensive testing support for OpenTelemetry Java SDK applications with AssertJ assertions, in-memory exporters, and JUnit integration.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.opentelemetry/opentelemetry-sdk-testing@1.51.x

To install, run

npx @tessl/cli install tessl/maven-io-opentelemetry--opentelemetry-sdk-testing@1.51.0

index.mddocs/

OpenTelemetry SDK Testing

A comprehensive Java testing library that provides utilities for testing OpenTelemetry Java SDK applications. This library enables developers to write effective unit and integration tests for telemetry-enabled applications with fluent AssertJ-based assertions, in-memory exporters for capturing telemetry data during tests, JUnit integration for automatic setup and cleanup, test data builders, and time manipulation utilities.

Package Information

  • Package Name: opentelemetry-sdk-testing
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk-testing</artifactId>
  <version>1.51.0</version>
  <scope>test</scope>
</dependency>

Core Imports

// Main assertions entry point
import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.*;

// In-memory exporters for data collection
import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
import io.opentelemetry.sdk.testing.exporter.InMemoryMetricExporter;
import io.opentelemetry.sdk.testing.exporter.InMemoryLogRecordExporter;

// JUnit integration
import io.opentelemetry.sdk.testing.junit5.OpenTelemetryExtension;
import io.opentelemetry.sdk.testing.junit4.OpenTelemetryRule;

Basic Usage

import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.*;
import io.opentelemetry.sdk.testing.junit5.OpenTelemetryExtension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;

public class MyTelemetryTest {

    @RegisterExtension
    static final OpenTelemetryExtension otelTesting = OpenTelemetryExtension.create();

    @Test
    void testSpanCreation() {
        // Get the OpenTelemetry instance configured for testing
        OpenTelemetry openTelemetry = otelTesting.getOpenTelemetry();
        
        // Create a tracer and span
        Tracer tracer = openTelemetry.getTracer("test");
        Span span = tracer.spanBuilder("test-span")
            .setAttribute(AttributeKey.stringKey("key"), "value")
            .startSpan();
        span.end();

        // Assert on the captured span data
        assertThat(otelTesting.getSpans())
            .hasSize(1)
            .first()
            .hasName("test-span")
            .hasAttribute(AttributeKey.stringKey("key"), "value")
            .hasEnded();
    }
}

Architecture

The OpenTelemetry SDK Testing library is organized around testing the three pillars of observability:

  • Assertions: Fluent, type-safe assertions for validating telemetry data (spans, metrics, logs)
  • Data Collection: In-memory exporters and readers for capturing telemetry during tests
  • Test Integration: JUnit extensions that automatically configure OpenTelemetry for testing
  • Test Utilities: Builders for creating test data and utilities for controlling time and context

This design enables comprehensive testing of OpenTelemetry instrumentation by providing both the infrastructure to collect telemetry data during tests and powerful assertion capabilities to validate the captured data.

Capabilities

AssertJ-Based Assertions

Comprehensive fluent assertions for validating spans, metrics, logs, and their associated attributes, events, and metadata. Built on AssertJ for familiar and powerful assertion syntax.

// Entry point for all assertions
class OpenTelemetryAssertions {
    static SpanDataAssert assertThat(SpanData spanData);
    static MetricAssert assertThat(MetricData metricData);
    static LogRecordDataAssert assertThat(LogRecordData logRecord);
    static AttributesAssert assertThat(Attributes attributes);
    static EventDataAssert assertThat(EventData eventData);
}

// Core assertion classes
class SpanDataAssert {
    SpanDataAssert hasName(String name);
    SpanDataAssert hasAttribute(AttributeKey<T> key, T value);
    SpanDataAssert hasEnded();
    // ... many more assertion methods
}

class MetricAssert {
    MetricAssert hasName(String name);
    MetricAssert hasDoubleGaugeSatisfying(Consumer<DoubleGaugeAssert> assertion);
    // ... many more assertion methods
}

Assertions

In-Memory Exporters

In-memory exporters for collecting spans, metrics, and logs during tests, providing easy access to captured telemetry data for validation.

class InMemorySpanExporter {
    static InMemorySpanExporter create();
    List<SpanData> getFinishedSpanItems();
    void reset();
}

class InMemoryMetricExporter {
    static InMemoryMetricExporter create();
    List<MetricData> getFinishedMetricItems();
    void reset();
}

class InMemoryLogRecordExporter {
    static InMemoryLogRecordExporter create();
    List<LogRecordData> getFinishedLogRecordItems();
    void reset();
}

class InMemoryMetricReader {
    static InMemoryMetricReader create();
    Collection<MetricData> collectAllMetrics();
}

Exporters

JUnit Integration

JUnit 4 and JUnit 5 extensions that automatically configure OpenTelemetry SDK for testing with convenient access to collected telemetry data.

// JUnit 5 Extension
class OpenTelemetryExtension {
    static OpenTelemetryExtension create();
    OpenTelemetry getOpenTelemetry();
    List<SpanData> getSpans();
    List<MetricData> getMetrics();
    List<LogRecordData> getLogRecords();
    TracesAssert assertTraces();
    void clearSpans();
    void clearMetrics();
    void clearLogRecords();
}

// JUnit 4 Rule
class OpenTelemetryRule {
    static OpenTelemetryRule create();
    OpenTelemetry getOpenTelemetry();
    List<SpanData> getSpans();
    List<MetricData> getMetrics();
    List<LogRecordData> getLogRecords();
    void clearSpans();
    void clearMetrics();
    void clearLogRecords();
}

JUnit Integration

Test Data Builders

Builder classes for creating test instances of telemetry data with full control over all properties and metadata.

class TestSpanData {
    static Builder builder();
    
    static class Builder {
        Builder setName(String name);
        Builder setSpanContext(SpanContext context);
        Builder setAttributes(Attributes attributes);
        Builder setEvents(List<EventData> events);
        Builder setStatus(StatusData status);
        TestSpanData build();
    }
}

class TestMetricData {
    static Builder builder();
    
    static class Builder {
        Builder setName(String name);
        Builder setDoubleGaugeData(GaugeData<DoublePointData> data);
        Builder setHistogramData(HistogramData data);
        TestMetricData build();
    }
}

class TestLogRecordData {
    static Builder builder();
    
    static class Builder {
        Builder setBody(String body);
        Builder setSeverity(Severity severity);
        Builder setAttributes(Attributes attributes);
        TestLogRecordData build();
    }
}

Test Builders

Time and Context Utilities

Utilities for controlling time during tests and managing context storage for test isolation and deterministic behavior.

class TestClock {
    static TestClock create();
    static TestClock create(Instant instant);
    void setTime(Instant instant);
    void advance(Duration duration);
    long now();
}

class SettableContextStorageProvider {
    static void setContextStorage(ContextStorage storage);
    static ContextStorage getContextStorage();
}

Utilities

Types

Core types used throughout the testing library:

// OpenTelemetry core types (from main SDK)
interface SpanData { /* spans captured during tests */ }
interface MetricData { /* metrics captured during tests */ }
interface LogRecordData { /* logs captured during tests */ }
interface Attributes { /* key-value attributes */ }
interface EventData { /* span events */ }
class AttributeKey<T> { /* typed attribute keys */ }

// AssertJ assertion types
class SpanDataAssert extends AbstractAssert<SpanDataAssert, SpanData> { }
class MetricAssert extends AbstractAssert<MetricAssert, MetricData> { }
class LogRecordDataAssert extends AbstractAssert<LogRecordDataAssert, LogRecordData> { }
class AttributesAssert extends AbstractAssert<AttributesAssert, Attributes> { }

// Test data builder types
class TestSpanData implements SpanData { }
class TestMetricData implements MetricData { }
class TestLogRecordData implements LogRecordData { }

// Time control
interface Clock { 
    long now(); 
    long nanoTime(); 
}