fix: improve psalm for fluent interface

Author: cedricziel

src/Utils/Test/src/Fluent/SpanAssertion.php

@@ -231,7 +231,7 @@ public function withAttributes(array $attributes): self
      *
      * @psalm-suppress PossiblyUnusedMethod
      *
-     * @param int|Constraint $code The expected status code
+     * @param string|Constraint $code The expected status code
      * @param string|Constraint|null $description The expected status description
      * @throws TraceAssertionFailedException
      * @return self
@@ -509,6 +509,21 @@ public function hasChild($name): SpanAssertion
         return new SpanAssertion($matchingSpan, $this->traceAssertion, $this, $this->expectedStructure, $this->actualStructure);
     }
 
+    /**
+     * Assert that the span has a root span with the given name.
+     * This is a convenience method that delegates to the trace assertion.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
+     *
+     * @param string|Constraint $name The expected name of the root span
+     * @throws TraceAssertionFailedException
+     * @return SpanAssertion
+     */
+    public function hasRootSpan($name): SpanAssertion
+    {
+        return $this->traceAssertion->hasRootSpan($name);
+    }
+
     /**
      * Assert that the span has the expected number of children.
      *

src/Utils/Test/src/Fluent/SpanEventAssertion.php

@@ -155,6 +155,7 @@ public function withAttributes(array $attributes): self
     /**
      * Return to the parent span assertion.
      *
+     * @psalm-suppress UnusedMethodCall
      * @return SpanAssertion
      */
     public function end(): SpanAssertion

src/Utils/Test/src/Fluent/TraceAssertion.php

@@ -139,6 +139,74 @@ public function hasRootSpan($name): SpanAssertion
         return new SpanAssertion($matchingSpan, $this, null, $this->expectedStructure, $this->actualStructure);
     }
 
+    /**
+     * Assert that the trace has a child span with the expected name.
+     *
+     * @param string|Constraint $name The expected child span name
+     * @throws TraceAssertionFailedException
+     * @return SpanAssertion
+     */
+    public function hasChild($name): SpanAssertion
+    {
+        // Find the matching span
+        $matchingSpan = null;
+
+        if ($name instanceof Constraint) {
+            foreach ($this->spans as $span) {
+                try {
+                    Assert::assertThat(
+                        $span->getName(),
+                        $name,
+                        'Span name does not match constraint'
+                    );
+                    $matchingSpan = $span;
+
+                    break;
+                } catch (AssertionFailedError $e) {
+                    // This span doesn't match the constraint, skip it
+                    continue;
+                }
+            }
+        } else {
+            foreach ($this->spans as $span) {
+                if ($span->getName() === $name) {
+                    $matchingSpan = $span;
+
+                    break;
+                }
+            }
+        }
+
+        if (!$matchingSpan) {
+            // Record the actual result
+            $this->actualStructure[] = [
+                'type' => 'missing_child_span',
+                'expected_name' => $name instanceof Constraint ? 'constraint' : $name,
+                'available_spans' => array_map(function ($span) {
+                    return $span->getName();
+                }, $this->spans),
+            ];
+
+            throw new TraceAssertionFailedException(
+                sprintf(
+                    'No span matching name "%s" found',
+                    $name instanceof Constraint ? 'constraint' : $name
+                ),
+                $this->expectedStructure,
+                $this->actualStructure
+            );
+        }
+
+        // Record the actual result
+        $this->actualStructure[] = [
+            'type' => 'child_span',
+            'name' => $matchingSpan->getName(),
+            'span' => $matchingSpan,
+        ];
+
+        return new SpanAssertion($matchingSpan, $this, null, $this->expectedStructure, $this->actualStructure);
+    }
+
     /**
      * Assert that the trace has the expected number of root spans.
      *
@@ -219,6 +287,17 @@ public function isStrict(): bool
         return $this->strict;
     }
 
+    /**
+     * Return the trace assertion itself.
+     * This method is used to maintain a consistent fluent interface.
+     *
+     * @return self
+     */
+    public function end(): self
+    {
+        return $this;
+    }
+
     /**
      * Converts spans to an array if they are in a different format.
      *

src/Utils/Test/tests/Unit/TraceAssertionFailedExceptionTest.php

@@ -146,6 +146,7 @@ public function test_trace_assertion_failed_exception_provides_visual_diff_for_m
 
     /**
      * Test that the TraceAssertionFailedException provides a visual diff when a span event is missing.
+     * @psalm-suppress UnusedMethodCall
      */
     public function test_trace_assertion_failed_exception_provides_visual_diff_for_missing_event(): void
     {