Download the PHP package open-telemetry/test-utils without Composer

This is a read-only subtree split of https://github.com/open-telemetry/opentelemetry-php-contrib.

OpenTelemetry Test Utilities

This package provides testing utilities for OpenTelemetry PHP instrumentations. It includes tools to help test and validate trace structures, span relationships, and other OpenTelemetry-specific functionality.

Features

TraceStructureAssertionTrait

The TraceStructureAssertionTrait provides methods to assess if spans match an expected trace structure. It's particularly useful for testing complex trace hierarchies and relationships between spans.

Key features:

• Support for hierarchical span relationships
• Verification of span names, kinds, attributes, events, and status
• Flexible matching with strict and non-strict modes
• Support for PHPUnit matchers/constraints for more flexible assertions
• Detailed error messages for failed assertions
• Two interfaces: array-based and fluent

Requirements

• PHP 7.4 or higher
• OpenTelemetry SDK and API (for testing)
• PHPUnit 9.5 or higher

Usage

TraceStructureAssertionTrait

Add the trait to your test class:

Array-Based Interface

Use the assertTraceStructure method to verify trace structures using an array-based approach:

The assertTraceStructure method takes the following parameters:

• $spans: An array or ArrayObject of spans (typically from an InMemoryExporter)
• $expectedStructure: An array defining the expected structure of the trace
• $strict (optional): Whether to perform strict matching (all attributes must match)

Fluent Interface

Use the assertTrace method to verify trace structures using a fluent, chainable interface:

The fluent interface provides the following methods:

TraceAssertion:

• hasRootSpan(string|Constraint $name): Assert that the trace has a root span with the given name
• hasRootSpans(int $count): Assert that the trace has the expected number of root spans
• inStrictMode(): Enable strict mode for all assertions

SpanAssertion:

• withKind(int|Constraint $kind): Assert that the span has the expected kind
• withAttribute(string $key, mixed|Constraint $value): Assert that the span has an attribute with the expected key and value
• withAttributes(array $attributes): Assert that the span has the expected attributes
• withStatus(int|Constraint $code, string|Constraint|null $description = null): Assert that the span has the expected status
• hasEvent(string|Constraint $name): Assert that the span has an event with the expected name
• hasChild(string|Constraint $name): Assert that the span has a child span with the expected name
• hasChildren(int $count): Assert that the span has the expected number of children
• end(): Return to the parent assertion

SpanEventAssertion:

• withAttribute(string $key, mixed|Constraint $value): Assert that the event has an attribute with the expected key and value
• withAttributes(array $attributes): Assert that the event has the expected attributes
• end(): Return to the parent span assertion

Using PHPUnit Matchers

You can use PHPUnit constraints/matchers for more flexible assertions with both interfaces:

Array-Based Interface with Matchers

Fluent Interface with Matchers

Supported PHPUnit matchers include:

• StringContains for partial string matching
• RegularExpression for pattern matching
• IsIdentical for strict equality
• IsEqual for loose equality
• IsType for type checking
• Callback for custom validation logic

Installation via composer

Installing dependencies and executing tests

From the Test Utils subdirectory: