0
# OpenTelemetry SDK Testing
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: opentelemetry-sdk-testing
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>io.opentelemetry</groupId>
13
    <artifactId>opentelemetry-sdk-testing</artifactId>
14
    <version>1.51.0</version>
15
    <scope>test</scope>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
// Main assertions entry point
23
import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.*;
24

25
// In-memory exporters for data collection
26
import io.opentelemetry.sdk.testing.exporter.InMemorySpanExporter;
27
import io.opentelemetry.sdk.testing.exporter.InMemoryMetricExporter;
28
import io.opentelemetry.sdk.testing.exporter.InMemoryLogRecordExporter;
29

30
// JUnit integration
31
import io.opentelemetry.sdk.testing.junit5.OpenTelemetryExtension;
32
import io.opentelemetry.sdk.testing.junit4.OpenTelemetryRule;
33
```
34

35
## Basic Usage
36

37
```java
38
import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.*;
39
import io.opentelemetry.sdk.testing.junit5.OpenTelemetryExtension;
40
import org.junit.jupiter.api.Test;
41
import org.junit.jupiter.api.extension.RegisterExtension;
42

43
public class MyTelemetryTest {
44

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

48
    @Test
49
    void testSpanCreation() {
50
        // Get the OpenTelemetry instance configured for testing
51
        OpenTelemetry openTelemetry = otelTesting.getOpenTelemetry();
52
        
53
        // Create a tracer and span
54
        Tracer tracer = openTelemetry.getTracer("test");
55
        Span span = tracer.spanBuilder("test-span")
56
            .setAttribute(AttributeKey.stringKey("key"), "value")
57
            .startSpan();
58
        span.end();
59

60
        // Assert on the captured span data
61
        assertThat(otelTesting.getSpans())
62
            .hasSize(1)
63
            .first()
64
            .hasName("test-span")
65
            .hasAttribute(AttributeKey.stringKey("key"), "value")
66
            .hasEnded();
67
    }
68
}
69
```
70

71
## Architecture
72

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

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

80
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.
81

82
## Capabilities
83

84
### AssertJ-Based Assertions
85

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

88
```java { .api }
89
// Entry point for all assertions
90
class OpenTelemetryAssertions {
91
    static SpanDataAssert assertThat(SpanData spanData);
92
    static MetricAssert assertThat(MetricData metricData);
93
    static LogRecordDataAssert assertThat(LogRecordData logRecord);
94
    static AttributesAssert assertThat(Attributes attributes);
95
    static EventDataAssert assertThat(EventData eventData);
96
}
97

98
// Core assertion classes
99
class SpanDataAssert {
100
    SpanDataAssert hasName(String name);
101
    SpanDataAssert hasAttribute(AttributeKey<T> key, T value);
102
    SpanDataAssert hasEnded();
103
    // ... many more assertion methods
104
}
105

106
class MetricAssert {
107
    MetricAssert hasName(String name);
108
    MetricAssert hasDoubleGaugeSatisfying(Consumer<DoubleGaugeAssert> assertion);
109
    // ... many more assertion methods
110
}
111
```
112

113
[Assertions](./assertions.md)
114

115
### In-Memory Exporters
116

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

119
```java { .api }
120
class InMemorySpanExporter {
121
    static InMemorySpanExporter create();
122
    List<SpanData> getFinishedSpanItems();
123
    void reset();
124
}
125

126
class InMemoryMetricExporter {
127
    static InMemoryMetricExporter create();
128
    List<MetricData> getFinishedMetricItems();
129
    void reset();
130
}
131

132
class InMemoryLogRecordExporter {
133
    static InMemoryLogRecordExporter create();
134
    List<LogRecordData> getFinishedLogRecordItems();
135
    void reset();
136
}
137

138
class InMemoryMetricReader {
139
    static InMemoryMetricReader create();
140
    Collection<MetricData> collectAllMetrics();
141
}
142
```
143

144
[Exporters](./exporters.md)
145

146
### JUnit Integration
147

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

150
```java { .api }
151
// JUnit 5 Extension
152
class OpenTelemetryExtension {
153
    static OpenTelemetryExtension create();
154
    OpenTelemetry getOpenTelemetry();
155
    List<SpanData> getSpans();
156
    List<MetricData> getMetrics();
157
    List<LogRecordData> getLogRecords();
158
    TracesAssert assertTraces();
159
    void clearSpans();
160
    void clearMetrics();
161
    void clearLogRecords();
162
}
163

164
// JUnit 4 Rule
165
class OpenTelemetryRule {
166
    static OpenTelemetryRule create();
167
    OpenTelemetry getOpenTelemetry();
168
    List<SpanData> getSpans();
169
    List<MetricData> getMetrics();
170
    List<LogRecordData> getLogRecords();
171
    void clearSpans();
172
    void clearMetrics();
173
    void clearLogRecords();
174
}
175
```
176

177
[JUnit Integration](./junit-integration.md)
178

179
### Test Data Builders
180

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

183
```java { .api }
184
class TestSpanData {
185
    static Builder builder();
186
    
187
    static class Builder {
188
        Builder setName(String name);
189
        Builder setSpanContext(SpanContext context);
190
        Builder setAttributes(Attributes attributes);
191
        Builder setEvents(List<EventData> events);
192
        Builder setStatus(StatusData status);
193
        TestSpanData build();
194
    }
195
}
196

197
class TestMetricData {
198
    static Builder builder();
199
    
200
    static class Builder {
201
        Builder setName(String name);
202
        Builder setDoubleGaugeData(GaugeData<DoublePointData> data);
203
        Builder setHistogramData(HistogramData data);
204
        TestMetricData build();
205
    }
206
}
207

208
class TestLogRecordData {
209
    static Builder builder();
210
    
211
    static class Builder {
212
        Builder setBody(String body);
213
        Builder setSeverity(Severity severity);
214
        Builder setAttributes(Attributes attributes);
215
        TestLogRecordData build();
216
    }
217
}
218
```
219

220
[Test Builders](./test-builders.md)
221

222
### Time and Context Utilities
223

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

226
```java { .api }
227
class TestClock {
228
    static TestClock create();
229
    static TestClock create(Instant instant);
230
    void setTime(Instant instant);
231
    void advance(Duration duration);
232
    long now();
233
}
234

235
class SettableContextStorageProvider {
236
    static void setContextStorage(ContextStorage storage);
237
    static ContextStorage getContextStorage();
238
}
239
```
240

241
[Utilities](./utilities.md)
242

243
## Types
244

245
Core types used throughout the testing library:
246

247
```java { .api }
248
// OpenTelemetry core types (from main SDK)
249
interface SpanData { /* spans captured during tests */ }
250
interface MetricData { /* metrics captured during tests */ }
251
interface LogRecordData { /* logs captured during tests */ }
252
interface Attributes { /* key-value attributes */ }
253
interface EventData { /* span events */ }
254
class AttributeKey<T> { /* typed attribute keys */ }
255

256
// AssertJ assertion types
257
class SpanDataAssert extends AbstractAssert<SpanDataAssert, SpanData> { }
258
class MetricAssert extends AbstractAssert<MetricAssert, MetricData> { }
259
class LogRecordDataAssert extends AbstractAssert<LogRecordDataAssert, LogRecordData> { }
260
class AttributesAssert extends AbstractAssert<AttributesAssert, Attributes> { }
261

262
// Test data builder types
263
class TestSpanData implements SpanData { }
264
class TestMetricData implements MetricData { }
265
class TestLogRecordData implements LogRecordData { }
266

267
// Time control
268
interface Clock { 
269
    long now(); 
270
    long nanoTime(); 
271
}
272
```