test: cover nested listener span hierarchy and context restoration

An outer listener that dispatches a second event (handled by an inner
listener) must produce Trace -> outer listener span -> inner listener
span, and each EventListenerTracer scope must restore its parent's
context as it unwinds.

- success path: inner span is parented to the outer span, the live
  context each listener observes is its own span, the outer listener's
  context is restored once the inner listener returns, and the bare
  trace context is restored once the outer listener returns.
- failure path: an inner listener throwing fails the inner span,
  restores the outer listener's context before the exception unwinds
  further, fails the outer span as the exception propagates through it,
  and leaves no span context on the tracer afterwards.

Adds the OrderShipped fixture event for the nested dispatch. No
production changes: the existing implementation already behaves
correctly.

Author: AdilAzhari

tests/Feature/Tracing/EventTracingTest.php

@@ -6,9 +6,11 @@
 use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Queue;
 use LaravelTrace\LaravelTrace\Contracts\Tracer;
+use LaravelTrace\LaravelTrace\Span\Span;
 use LaravelTrace\LaravelTrace\Span\SpanStatus;
 use LaravelTrace\LaravelTrace\Span\SpanType;
 use LaravelTrace\LaravelTrace\Tests\Fixtures\Events\OrderCreated;
+use LaravelTrace\LaravelTrace\Tests\Fixtures\Events\OrderShipped;
 use LaravelTrace\LaravelTrace\Tests\Fixtures\Listeners\QueuedOrderNotifier;
 use LaravelTrace\LaravelTrace\Tests\Fixtures\Listeners\SendOrderConfirmation;
 use LaravelTrace\LaravelTrace\Tracing\InMemorySpanRecorder;
@@ -127,3 +129,138 @@ function (OrderCreated $event) use (&$executed): void {
     expect(app(InMemorySpanRecorder::class)->all())
         ->toBeEmpty();
 });
+
+it('nests listener spans and restores each parent context as listeners finish', function (): void {
+    $tracer = app(Tracer::class);
+
+    $contextInsideOuter = null;
+    $contextInsideInner = null;
+    $contextInOuterAfterInner = null;
+
+    Event::listen(
+        OrderShipped::class,
+        function () use ($tracer, &$contextInsideInner): void {
+            $contextInsideInner = $tracer->context();
+        },
+    );
+
+    Event::listen(
+        OrderCreated::class,
+        function () use ($tracer, &$contextInsideOuter, &$contextInOuterAfterInner): void {
+            $contextInsideOuter = $tracer->context();
+
+            Event::dispatch(new OrderShipped(orderId: 1));
+
+            $contextInOuterAfterInner = $tracer->context();
+        },
+    );
+
+    $trace = $tracer->start('test');
+
+    Event::dispatch(new OrderCreated(orderId: 1));
+
+    $spans = app(InMemorySpanRecorder::class)->all();
+
+    $outerSpan = collect($spans)
+        ->first(fn (Span $span): bool => $span->parentId === null);
+
+    $innerSpan = collect($spans)
+        ->first(fn (Span $span): bool => $span->parentId !== null);
+
+    // Trace -> outer listener span -> inner listener span
+    expect($spans)
+        ->toHaveCount(2)
+        ->and($outerSpan->type)
+        ->toBe(SpanType::Listener)
+        ->and($innerSpan->type)
+        ->toBe(SpanType::Listener)
+        ->and($outerSpan->traceId->value)
+        ->toBe($trace->id->value)
+        ->and($innerSpan->traceId->value)
+        ->toBe($trace->id->value)
+        ->and($innerSpan->parentId->value)
+        ->toBe($outerSpan->id->value)
+        ->and($outerSpan->status)
+        ->toBe(SpanStatus::Completed)
+        ->and($innerSpan->status)
+        ->toBe(SpanStatus::Completed);
+
+    // The live context each listener saw while running.
+    expect($contextInsideOuter?->spanId?->value)
+        ->toBe($outerSpan->id->value)
+        ->and($contextInsideInner?->spanId?->value)
+        ->toBe($innerSpan->id->value);
+
+    // When the inner listener finished, the outer listener's context was restored.
+    expect($contextInOuterAfterInner?->spanId?->value)
+        ->toBe($outerSpan->id->value);
+
+    // When the outer listener finished, the original trace context was restored.
+    expect($tracer->context()?->traceId->value)
+        ->toBe($trace->id->value)
+        ->and($tracer->context()?->spanId)
+        ->toBeNull();
+});
+
+it('fails the inner listener span, propagates, and restores the outer listener context', function (): void {
+    $tracer = app(Tracer::class);
+
+    $contextInOuterWhenInnerThrew = null;
+
+    Event::listen(
+        OrderShipped::class,
+        function (): void {
+            throw new RuntimeException('Inner listener failed.');
+        },
+    );
+
+    Event::listen(
+        OrderCreated::class,
+        function () use ($tracer, &$contextInOuterWhenInnerThrew): void {
+            try {
+                Event::dispatch(new OrderShipped(orderId: 1));
+            } catch (RuntimeException $exception) {
+                $contextInOuterWhenInnerThrew = $tracer->context();
+
+                throw $exception;
+            }
+        },
+    );
+
+    $trace = $tracer->start('test');
+
+    expect(fn () => Event::dispatch(new OrderCreated(orderId: 1)))
+        ->toThrow(RuntimeException::class, 'Inner listener failed.');
+
+    $spans = app(InMemorySpanRecorder::class)->all();
+
+    $outerSpan = collect($spans)
+        ->first(fn (Span $span): bool => $span->parentId === null);
+
+    $innerSpan = collect($spans)
+        ->first(fn (Span $span): bool => $span->parentId !== null);
+
+    expect($spans)
+        ->toHaveCount(2)
+        ->and($innerSpan->parentId->value)
+        ->toBe($outerSpan->id->value)
+        ->and($innerSpan->status)
+        ->toBe(SpanStatus::Failed)
+        ->and($innerSpan->error?->type)
+        ->toBe(RuntimeException::class)
+        ->and($outerSpan->status)
+        ->toBe(SpanStatus::Failed)
+        ->and($outerSpan->error?->type)
+        ->toBe(RuntimeException::class);
+
+    // The inner span's failure restored the outer listener's context before the
+    // exception unwound any further.
+    expect($contextInOuterWhenInnerThrew?->spanId?->value)
+        ->toBe($outerSpan->id->value);
+
+    // The outer span's failure restored the original trace context: nothing leaked.
+    expect($tracer->context()?->traceId->value)
+        ->toBe($trace->id->value)
+        ->and($tracer->context()?->spanId)
+        ->toBeNull();
+});

tests/Fixtures/Events/OrderShipped.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace LaravelTrace\LaravelTrace\Tests\Fixtures\Events;
+
+final readonly class OrderShipped
+{
+    public function __construct(
+        public int $orderId,
+    ) {}
+}