0
# AssertJ-Based Assertions
1

2
Comprehensive fluent assertions for validating OpenTelemetry telemetry data. Built on AssertJ, these assertions provide type-safe, readable validation of spans, metrics, logs, and their associated attributes, events, and metadata.
3

4
## Capabilities
5

6
### OpenTelemetryAssertions Entry Point
7

8
Main entry point providing factory methods for all OpenTelemetry assertion types.
9

10
```java { .api }
11
class OpenTelemetryAssertions extends Assertions {
12
    // Primary assertion factory methods
13
    static SpanDataAssert assertThat(SpanData spanData);
14
    static MetricAssert assertThat(MetricData metricData);
15
    static LogRecordDataAssert assertThat(LogRecordData logRecord);
16
    static AttributesAssert assertThat(Attributes attributes);
17
    static EventDataAssert assertThat(EventData eventData);
18
    
19
    // Attribute entry creation utilities
20
    static Map.Entry<AttributeKey<String>, String> attributeEntry(String key, String value);
21
    static Map.Entry<AttributeKey<Boolean>, Boolean> attributeEntry(String key, boolean value);
22
    static Map.Entry<AttributeKey<Long>, Long> attributeEntry(String key, long value);
23
    static Map.Entry<AttributeKey<Double>, Double> attributeEntry(String key, double value);
24
    static Map.Entry<AttributeKey<List<String>>, List<String>> attributeEntry(String key, String... value);
25
    static Map.Entry<AttributeKey<List<Boolean>>, List<Boolean>> attributeEntry(String key, boolean... value);
26
    static Map.Entry<AttributeKey<List<Long>>, List<Long>> attributeEntry(String key, long... value);
27
    static Map.Entry<AttributeKey<List<Double>>, List<Double>> attributeEntry(String key, double... value);
28
    
29
    // Attribute assertion builders
30
    static <T> AttributeAssertion satisfies(AttributeKey<T> key, Consumer<T> assertion);
31
    static <T> AttributeAssertion equalTo(AttributeKey<T> key, T value);
32
}
33
```
34

35
### Span Assertions
36

37
Comprehensive assertions for validating SpanData objects including identity, hierarchy, timing, attributes, events, links, and status.
38

39
```java { .api }
40
class SpanDataAssert extends AbstractAssert<SpanDataAssert, SpanData> {
41
    // Identity assertions
42
    SpanDataAssert hasTraceId(String traceId);
43
    SpanDataAssert hasSpanId(String spanId);
44
    SpanDataAssert hasName(String name);
45
    SpanDataAssert hasKind(SpanKind kind);
46
    
47
    // Hierarchy assertions
48
    SpanDataAssert hasParent(SpanData parent);
49
    SpanDataAssert hasParentSpanId(String parentSpanId);
50
    SpanDataAssert hasNoParent();
51
    
52
    // State assertions
53
    SpanDataAssert isSampled();
54
    SpanDataAssert isNotSampled();
55
    SpanDataAssert hasEnded();
56
    SpanDataAssert hasNotEnded();
57
    
58
    // Timing assertions
59
    SpanDataAssert startsAt(long epochNanos);
60
    SpanDataAssert startsAt(Instant timestamp);
61
    SpanDataAssert endsAt(long epochNanos);
62
    SpanDataAssert endsAt(Instant timestamp);
63
    
64
    // Attribute assertions
65
    SpanDataAssert hasAttribute(AttributeKey<T> key, T value);
66
    SpanDataAssert hasAttribute(AttributeAssertion assertion);
67
    SpanDataAssert hasAttributes(Attributes attributes);
68
    SpanDataAssert hasAttributesSatisfying(Consumer<Attributes> condition);
69
    SpanDataAssert hasAttributesSatisfying(AttributeAssertion... assertions);
70
    SpanDataAssert hasAttributesSatisfyingExactly(AttributeAssertion... assertions);
71
    
72
    // Event assertions
73
    SpanDataAssert hasException(Throwable exception);
74
    SpanDataAssert hasEvents(EventData... events);
75
    SpanDataAssert hasEventsSatisfying(Consumer<List<? extends EventData>> condition);
76
    SpanDataAssert hasEventsSatisfyingExactly(Consumer<EventDataAssert>... assertions);
77
    
78
    // Link assertions
79
    SpanDataAssert hasLinks(LinkData... links);
80
    SpanDataAssert hasLinksSatisfying(Consumer<List<? extends LinkData>> condition);
81
    
82
    // Status assertions
83
    SpanDataAssert hasStatus(StatusData status);
84
    SpanDataAssert hasStatusSatisfying(Consumer<StatusDataAssert> condition);
85
    
86
    // Metadata assertions
87
    SpanDataAssert hasResource(Resource resource);
88
    SpanDataAssert hasResourceSatisfying(Consumer<ResourceAssert> resource);
89
    SpanDataAssert hasInstrumentationScopeInfo(InstrumentationScopeInfo scope);
90
    SpanDataAssert hasTotalRecordedEvents(int count);
91
    SpanDataAssert hasTotalRecordedLinks(int count);
92
    SpanDataAssert hasTotalAttributeCount(int count);
93
}
94
```
95

96
Usage examples:
97

98
```java
99
// Basic span validation
100
assertThat(span)
101
    .hasName("http-request")
102
    .hasKind(SpanKind.CLIENT)
103
    .hasEnded()
104
    .hasAttribute(AttributeKey.stringKey("http.method"), "GET")
105
    .hasAttribute(AttributeKey.longKey("http.status_code"), 200L);
106

107
// Complex attribute validation with custom assertions
108
assertThat(span)
109
    .hasAttributesSatisfying(
110
        equalTo(AttributeKey.stringKey("service.name"), "my-service"),
111
        satisfies(AttributeKey.longKey("duration"), duration -> 
112
            assertThat(duration).isBetween(100L, 5000L))
113
    );
114

115
// Event validation
116
assertThat(span)
117
    .hasEventsSatisfyingExactly(
118
        event -> assertThat(event).hasName("request.start"),
119
        event -> assertThat(event).hasName("request.end")
120
    );
121
```
122

123
### Metric Assertions
124

125
Assertions for validating MetricData objects with support for all metric types (gauges, sums, histograms, exponential histograms, summaries).
126

127
```java { .api }
128
class MetricAssert extends AbstractAssert<MetricAssert, MetricData> {
129
    // Basic metric properties
130
    MetricAssert hasName(String name);
131
    MetricAssert hasDescription(String description);
132
    MetricAssert hasUnit(String unit);
133
    
134
    // Metadata assertions
135
    MetricAssert hasResource(Resource resource);
136
    MetricAssert hasResourceSatisfying(Consumer<ResourceAssert> resource);
137
    MetricAssert hasInstrumentationScopeInfo(InstrumentationScopeInfo scope);
138
    
139
    // Data type specific assertions
140
    MetricAssert hasDoubleGaugeSatisfying(Consumer<DoubleGaugeAssert> assertion);
141
    MetricAssert hasLongGaugeSatisfying(Consumer<LongGaugeAssert> assertion);
142
    MetricAssert hasDoubleSumSatisfying(Consumer<DoubleSumAssert> assertion);
143
    MetricAssert hasLongSumSatisfying(Consumer<LongSumAssert> assertion);
144
    MetricAssert hasHistogramSatisfying(Consumer<HistogramAssert> assertion);
145
    MetricAssert hasExponentialHistogramSatisfying(Consumer<ExponentialHistogramAssert> assertion);
146
    MetricAssert hasSummarySatisfying(Consumer<SummaryAssert> assertion);
147
}
148
```
149

150
Usage examples:
151

152
```java
153
// Gauge metric validation
154
assertThat(gaugeMetric)
155
    .hasName("memory.usage")
156
    .hasUnit("bytes")
157
    .hasDoubleGaugeSatisfying(gauge ->
158
        gauge.hasPointsSatisfying(point ->
159
            point.hasValue(1024.0)
160
                 .hasAttributes(attributeEntry("heap", "used"))
161
        )
162
    );
163

164
// Histogram metric validation
165
assertThat(histogramMetric)
166
    .hasName("request.duration")
167
    .hasUnit("ms")
168
    .hasHistogramSatisfying(histogram ->
169
        histogram.hasPointsSatisfying(point ->
170
            point.hasCount(100)
171
                 .hasSum(5000.0)
172
                 .hasBucketCounts(10, 30, 40, 20)
173
        )
174
    );
175
```
176

177
### Log Record Assertions
178

179
Assertions for validating LogRecordData objects including body, severity, timestamps, and associated context.
180

181
```java { .api }
182
class LogRecordDataAssert extends AbstractAssert<LogRecordDataAssert, LogRecordData> {
183
    // Basic log properties
184
    LogRecordDataAssert hasBody(String body);
185
    LogRecordDataAssert hasBodyValue(Value<?> body);
186
    LogRecordDataAssert hasSeverity(Severity severity);
187
    LogRecordDataAssert hasSeverityText(String severityText);
188
    
189
    // Timing assertions
190
    LogRecordDataAssert hasTimestamp(long epochNanos);
191
    LogRecordDataAssert hasTimestamp(Instant instant);
192
    LogRecordDataAssert hasObservedTimestamp(long epochNanos);
193
    LogRecordDataAssert hasObservedTimestamp(Instant instant);
194
    
195
    // Context assertions
196
    LogRecordDataAssert hasSpanContext(SpanContext spanContext);
197
    LogRecordDataAssert hasResource(Resource resource);
198
    LogRecordDataAssert hasResourceSatisfying(Consumer<ResourceAssert> resource);
199
    LogRecordDataAssert hasInstrumentationScopeInfo(InstrumentationScopeInfo scope);
200
    
201
    // Attribute assertions
202
    LogRecordDataAssert hasAttributes(Attributes attributes);
203
    LogRecordDataAssert hasAttributesSatisfying(AttributeAssertion... assertions);
204
    LogRecordDataAssert hasTotalAttributeCount(int count);
205
}
206
```
207

208
Usage examples:
209

210
```java
211
// Basic log validation
212
assertThat(logRecord)
213
    .hasBody("Request completed successfully")
214
    .hasSeverity(Severity.INFO)
215
    .hasAttribute(AttributeKey.stringKey("service.name"), "my-service")
216
    .hasSpanContext(span.getSpanContext());
217

218
// Timestamp validation
219
assertThat(logRecord)
220
    .hasTimestamp(Instant.parse("2023-01-01T12:00:00Z"))
221
    .hasObservedTimestamp(Instant.parse("2023-01-01T12:00:00.100Z"));
222
```
223

224
### Attributes Assertions
225

226
Assertions for validating Attributes collections with support for key existence, value matching, and collection properties.
227

228
```java { .api }
229
class AttributesAssert extends AbstractAssert<AttributesAssert, Attributes> {
230
    // Entry assertions
231
    AttributesAssert containsEntry(AttributeKey<T> key, T value);
232
    AttributesAssert containsKey(AttributeKey<?> key);
233
    AttributesAssert doesNotContainKey(AttributeKey<?> key);
234
    
235
    // Collection assertions
236
    AttributesAssert containsOnly(Map.Entry<? extends AttributeKey<?>, ?>... entries);
237
    AttributesAssert containsOnlyKeys(AttributeKey<?>... keys);
238
    AttributesAssert hasSize(int expectedSize);
239
    AttributesAssert isEmpty();
240
    AttributesAssert isEqualTo(Attributes expected);
241
    
242
    // Condition-based assertions
243
    AttributesAssert satisfies(Consumer<Attributes> condition);
244
}
245
```
246

247
### Traces Assertions
248

249
Assertions for collections of traces (grouped spans) with support for validating trace relationships and structure.
250

251
```java { .api }
252
class TracesAssert extends AbstractAssert<TracesAssert, Collection<List<SpanData>>> {
253
    // Factory methods
254
    static TracesAssert assertThat(List<SpanData> spanData);
255
    static TracesAssert assertThat(Collection<List<SpanData>> traces);
256
    
257
    // Trace collection assertions
258
    TracesAssert hasTracesSatisfyingExactly(Consumer<TraceAssert>... assertions);
259
    TracesAssert hasTracesSatisfyingExactly(Iterable<? extends Consumer<TraceAssert>> assertions);
260
}
261

262
class TraceAssert extends AbstractAssert<TraceAssert, List<SpanData>> {
263
    TraceAssert hasSpansSatisfyingExactly(Consumer<SpanDataAssert>... assertions);
264
    TraceAssert hasSize(int expectedSize);
265
}
266
```
267

268
### Specialized Metric Assertions
269

270
The library provides specialized assertion classes for each metric data type:
271

272
```java { .api }
273
// Gauge assertions
274
class DoubleGaugeAssert extends AbstractAssert<DoubleGaugeAssert, GaugeData<DoublePointData>> {
275
    DoubleGaugeAssert hasPointsSatisfying(Consumer<DoublePointAssert>... assertions);
276
}
277

278
class LongGaugeAssert extends AbstractAssert<LongGaugeAssert, GaugeData<LongPointData>> {
279
    LongGaugeAssert hasPointsSatisfying(Consumer<LongPointAssert>... assertions);
280
}
281

282
// Sum assertions
283
class DoubleSumAssert extends AbstractAssert<DoubleSumAssert, SumData<DoublePointData>> {
284
    DoubleSumAssert isMonotonic();
285
    DoubleSumAssert isNotMonotonic();
286
    DoubleSumAssert isCumulative();
287
    DoubleSumAssert isDelta();
288
    DoubleSumAssert hasPointsSatisfying(Consumer<DoublePointAssert>... assertions);
289
}
290

291
class LongSumAssert extends AbstractAssert<LongSumAssert, SumData<LongPointData>> {
292
    LongSumAssert isMonotonic();
293
    LongSumAssert isNotMonotonic();
294
    LongSumAssert isCumulative();
295
    LongSumAssert isDelta();
296
    LongSumAssert hasPointsSatisfying(Consumer<LongPointAssert>... assertions);
297
}
298

299
// Histogram assertions
300
class HistogramAssert extends AbstractAssert<HistogramAssert, HistogramData> {
301
    HistogramAssert hasPointsSatisfying(Consumer<HistogramPointAssert>... assertions);
302
}
303

304
class HistogramPointAssert extends AbstractPointAssert<HistogramPointAssert, HistogramPointData> {
305
    HistogramPointAssert hasSum(double expectedSum);
306
    HistogramPointAssert hasCount(long expectedCount);
307
    HistogramPointAssert hasBucketBoundaries(Double... expectedBoundaries);
308
    HistogramPointAssert hasBucketCounts(Long... expectedCounts);
309
    HistogramPointAssert hasExemplars(ExemplarData... expectedExemplars);
310
}
311

312
// Exponential histogram assertions
313
class ExponentialHistogramAssert extends AbstractAssert<ExponentialHistogramAssert, ExponentialHistogramData> {
314
    ExponentialHistogramAssert hasPointsSatisfying(Consumer<ExponentialHistogramPointAssert>... assertions);
315
}
316

317
class ExponentialHistogramPointAssert extends AbstractPointAssert<ExponentialHistogramPointAssert, ExponentialHistogramPointData> {
318
    ExponentialHistogramPointAssert hasSum(double expectedSum);
319
    ExponentialHistogramPointAssert hasCount(long expectedCount);
320
    ExponentialHistogramPointAssert hasScale(int expectedScale);
321
    ExponentialHistogramPointAssert hasZeroCount(long expectedZeroCount);
322
    ExponentialHistogramPointAssert hasPositiveBuckets(ExponentialHistogramBuckets expectedBuckets);
323
    ExponentialHistogramPointAssert hasNegativeBuckets(ExponentialHistogramBuckets expectedBuckets);
324
}
325

326
// Point data assertions
327
class DoublePointAssert extends AbstractPointAssert<DoublePointAssert, DoublePointData> {
328
    DoublePointAssert hasValue(double expectedValue);
329
    DoublePointAssert hasExemplars(DoubleExemplarData... expectedExemplars);
330
}
331

332
class LongPointAssert extends AbstractPointAssert<LongPointAssert, LongPointData> {
333
    LongPointAssert hasValue(long expectedValue);
334
    LongPointAssert hasExemplars(LongExemplarData... expectedExemplars);
335
}
336
```
337

338
### Support Assertions
339

340
Additional assertion classes for supporting data types:
341

342
```java { .api }
343
class EventDataAssert extends AbstractAssert<EventDataAssert, EventData> {
344
    EventDataAssert hasName(String name);
345
    EventDataAssert hasEpochNanos(long epochNanos);
346
    EventDataAssert hasTimestamp(Instant timestamp);
347
    EventDataAssert hasAttributes(Attributes attributes);
348
    EventDataAssert hasTotalAttributeCount(int count);
349
}
350

351
class StatusDataAssert extends AbstractAssert<StatusDataAssert, StatusData> {
352
    StatusDataAssert hasCode(StatusCode code);
353
    StatusDataAssert hasDescription(String description);
354
    StatusDataAssert isOk();
355
    StatusDataAssert isError();
356
    StatusDataAssert isUnset();
357
}
358

359
class ResourceAssert extends AbstractAssert<ResourceAssert, Resource> {
360
    ResourceAssert hasAttribute(AttributeKey<T> key, T value);
361
    ResourceAssert hasAttributes(Attributes attributes);
362
    ResourceAssert hasSchemaUrl(String schemaUrl);
363
}
364
```
365

366
## Types
367

368
```java { .api }
369
// Attribute assertion builder
370
class AttributeAssertion {
371
    static <T> AttributeAssertion satisfies(AttributeKey<T> key, Consumer<T> assertion);
372
    static <T> AttributeAssertion equalTo(AttributeKey<T> key, T value);
373
}
374

375
// Abstract base for point assertions
376
abstract class AbstractPointAssert<SELF extends AbstractPointAssert<SELF, ACTUAL>, ACTUAL extends PointData> 
377
    extends AbstractAssert<SELF, ACTUAL> {
378
    SELF hasStartEpochNanos(long expectedStartEpochNanos);
379
    SELF hasEpochNanos(long expectedEpochNanos);
380
    SELF hasAttributes(Attributes expectedAttributes);
381
    SELF hasAttribute(AttributeKey<T> key, T value);
382
}
383

384
// Functional interfaces for type-safe attribute assertions  
385
interface StringAssertConsumer extends Consumer<StringAssert> { }
386
interface BooleanAssertConsumer extends Consumer<BooleanAssert> { }
387
interface LongAssertConsumer extends Consumer<LongAssert> { }
388
interface DoubleAssertConsumer extends Consumer<DoubleAssert> { }
389
interface StringListAssertConsumer extends Consumer<ListAssert<String>> { }
390
interface BooleanListAssertConsumer extends Consumer<ListAssert<Boolean>> { }
391
interface LongListAssertConsumer extends Consumer<ListAssert<Long>> { }
392
interface DoubleListAssertConsumer extends Consumer<ListAssert<Double>> { }
393
```