WIP

Author: PerfectSlayer

dd-smoke-tests/src/main/java/datadog/smoketest/trace/SpanMatcher.java

@@ -17,20 +17,27 @@
 import java.util.regex.Pattern;
 
 /**
- * Thin span matcher for smoke tests, operating on the <em>serialized</em> {@link DecodedSpan} model
- * produced by both smoke backends (the in-process mock agent and the dd-apm-test-agent).
+ * The class is a helper class to verify span attributes on the {@link DecodedSpan} model produced
+ * by both smoke backends (the in-process mock agent and the dd-apm-test-agent).
  *
- * <p>This is deliberately separate from the in-process instrumentation DSL ({@code
- * datadog.trace.agent.test.assertions}, which matches on {@code DDSpan}); the two share only the
- * generic value matchers in {@code datadog.trace.junit.utils.assertions}. Only what a span carries
- * once serialized is matchable here: name/service/resource/type, error status, {@code meta} (string
- * tags), {@code metrics} (numeric tags), {@code meta_struct} (nested structured data), and parent
- * linkage.
+ * <p>To get a {@code SpanMatcher}, use the static factory method {@link #span()} and use it as a
+ * fluent builder to define the span matching constraints.
  *
- * <p>Parent linkage can be expressed by {@link #root()}, {@link #childOf(long) explicit id}, or —
- * for structural assertions within a sorted trace — by position with {@link #childOfIndex(int)} /
- * {@link #childOfPrevious()} (mirroring the instrumentation DSL). Use the {@link #span()} factory
- * as a fluent builder; unset constraints are not checked.
+ * <p>Span matching constraints cover only what a span carries once serialized:
+ *
+ * <ul>
+ *   <li>span service name with {@link #service(String)}
+ *   <li>span operation name with {@link #operationName(String)} and {@link #operationName(Pattern)}
+ *   <li>span resource name with {@link #resourceName(String)}, {@link #resourceName(Pattern)}, and
+ *       {@link #resourceName(Predicate)}
+ *   <li>span type with {@link #type(String)}
+ *   <li>span error status with {@link #error(boolean)}
+ *   <li>span parent linkage with {@link #root()}, {@link #childOf(long)}, {@link
+ *       #childOfIndex(int)}, and {@link #childOfPrevious()}
+ *   <li>span meta (string) tags with {@link #tag(String, Matcher)} and {@link #tag(String, String)}
+ *   <li>span metrics (numeric) tags with {@link #metric(String, Matcher)}
+ *   <li>span meta_struct (nested structured data) with {@link #metaStruct(String, Matcher)}
+ * </ul>
  */
 public final class SpanMatcher {
   private Matcher<String> serviceMatcher;
@@ -53,98 +60,203 @@ private SpanMatcher() {
     this.metaStructMatchers = new HashMap<>();
   }
 
-  /** Creates a new span matcher; configure it with the fluent methods below. */
+  /**
+   * Checks a span and its attributes.
+   *
+   * @return A new {@link SpanMatcher} instance to configure span matching constraints.
+   */
   public static SpanMatcher span() {
     return new SpanMatcher();
   }
 
+  /**
+   * Checks the span service name matches the given value.
+   *
+   * @param service The service name to match against.
+   * @return The current {@link SpanMatcher} instance updated with the specified service name
+   *     constraint.
+   */
   public SpanMatcher service(String service) {
     this.serviceMatcher = is(service);
     return this;
   }
 
+  /**
+   * Checks the span operation name matches the given value.
+   *
+   * @param operationName The operation name to match against.
+   * @return The current {@link SpanMatcher} instance updated with the specified operation name
+   *     constraint.
+   */
   public SpanMatcher operationName(String operationName) {
     this.operationNameMatcher = is(operationName);
     return this;
   }
 
+  /**
+   * Checks the span operation name matches the provided regular expression pattern.
+   *
+   * @param pattern The {@link Pattern} to match the operation name against.
+   * @return The current {@link SpanMatcher} instance updated with the specified operation name
+   *     constraint.
+   */
   public SpanMatcher operationName(Pattern pattern) {
     this.operationNameMatcher = matches(pattern);
     return this;
   }
 
+  /**
+   * Checks the span resource name matches the given value.
+   *
+   * @param resourceName The resource name to match against.
+   * @return The current {@link SpanMatcher} instance updated with the specified resource name
+   *     constraint.
+   */
   public SpanMatcher resourceName(String resourceName) {
     this.resourceNameMatcher = is(resourceName);
     return this;
   }
 
+  /**
+   * Checks the span resource name matches the provided regular expression pattern.
+   *
+   * @param pattern The {@link Pattern} used to match the resource name against.
+   * @return The current {@link SpanMatcher} instance updated with the specified resource name
+   *     constraint.
+   */
   public SpanMatcher resourceName(Pattern pattern) {
     this.resourceNameMatcher = matches(pattern);
     return this;
   }
 
+  /**
+   * Checks the span resource name matches the provided validator.
+   *
+   * @param validator The {@link Predicate} used to validate the resource name.
+   * @return The current {@link SpanMatcher} instance updated with the specified resource name
+   *     constraint.
+   */
   public SpanMatcher resourceName(Predicate<CharSequence> validator) {
     this.resourceNameMatcher = validates(validator);
     return this;
   }
 
+  /**
+   * Checks the span type matches the given value.
+   *
+   * @param type The span type to match against.
+   * @return The current {@link SpanMatcher} instance updated with the specified span type
+   *     constraint.
+   */
   public SpanMatcher type(String type) {
     this.typeMatcher = is(type);
     return this;
   }
 
-  /** Matches the span error status. */
+  /**
+   * Checks the span error status matches the given value.
+   *
+   * @param errored The expected error status.
+   * @return The current {@link SpanMatcher} instance updated with the specified error constraint.
+   */
   public SpanMatcher error(boolean errored) {
     this.errorMatcher = errored ? isTrue() : isFalse();
     return this;
   }
 
-  /** Matches a root span (no parent). */
+  /**
+   * Checks the span is a root span (i.e., a span with no parent).
+   *
+   * @return The current {@link SpanMatcher} instance with the root constraint applied.
+   */
   public SpanMatcher root() {
     this.parentIdMatcher = is(0L);
     this.parentSpanIndex = -1;
     return this;
   }
 
-  /** Matches a span whose parent is the given span id. */
+  /**
+   * Checks the span is a direct child of the specified parent span.
+   *
+   * @param parentSpanId The identifier of the parent span to match against.
+   * @return The current {@link SpanMatcher} instance with the child-of constraint applied.
+   */
   public SpanMatcher childOf(long parentSpanId) {
     this.parentIdMatcher = is(parentSpanId);
     this.parentSpanIndex = -1;
     return this;
   }
 
-  /** Matches a span whose parent is the span at {@code parentSpanIndex} in the (sorted) trace. */
+  /**
+   * Checks the span is a direct child of the span at the specified index in the trace.
+   *
+   * @param parentSpanIndex The index of the parent span in the trace.
+   * @return The current {@link SpanMatcher} instance with the child-of constraint applied.
+   */
   public SpanMatcher childOfIndex(int parentSpanIndex) {
     this.parentIdMatcher = null;
     this.parentSpanIndex = parentSpanIndex;
     return this;
   }
 
-  /** Matches a span whose parent is the immediately preceding span in the (sorted) trace. */
+  /**
+   * Checks the span is a direct child of the immediately preceding span in the trace.
+   *
+   * @return The current {@link SpanMatcher} instance with the child-of constraint applied.
+   */
   public SpanMatcher childOfPrevious() {
     this.parentIdMatcher = CHILD_OF_PREVIOUS_MATCHER;
     this.parentSpanIndex = -1;
     return this;
   }
 
-  /** Matches a {@code meta} (string) tag against the given matcher. */
+  /**
+   * Checks the span meta (string) tag matches the given matcher.
+   *
+   * @param name The name of the meta tag to match against.
+   * @param matcher The matcher to check the meta tag value.
+   * @return The current {@link SpanMatcher} instance updated with the specified meta tag
+   *     constraint.
+   */
   public SpanMatcher tag(String name, Matcher<String> matcher) {
     this.metaMatchers.put(name, matcher);
     return this;
   }
 
-  /** Matches a {@code meta} (string) tag against the given value. */
+  /**
+   * Checks the span meta (string) tag matches the given value.
+   *
+   * @param name The name of the meta tag to match against.
+   * @param value The expected meta tag value.
+   * @return The current {@link SpanMatcher} instance updated with the specified meta tag
+   *     constraint.
+   */
   public SpanMatcher tag(String name, String value) {
     this.metaMatchers.put(name, is(value));
     return this;
   }
 
-  /** Matches a {@code metrics} (numeric) tag against the given matcher. */
+  /**
+   * Checks the span metric (numeric) tag matches the given matcher.
+   *
+   * @param name The name of the metric tag to match against.
+   * @param matcher The matcher to check the metric tag value.
+   * @return The current {@link SpanMatcher} instance updated with the specified metric tag
+   *     constraint.
+   */
   public SpanMatcher metric(String name, Matcher<Number> matcher) {
     this.metricMatchers.put(name, matcher);
     return this;
   }
 
+  /**
+   * Checks the span meta_struct entry matches the given matcher.
+   *
+   * @param name The name of the meta_struct entry to match against.
+   * @param matcher The matcher to check the meta_struct entry value.
+   * @return The current {@link SpanMatcher} instance updated with the specified meta_struct
+   *     constraint.
+   */
   public SpanMatcher metaStruct(String name, Matcher<?> matcher) {
     this.metaStructMatchers.put(name, matcher);
     return this;
@@ -196,7 +308,9 @@ private void assertSpanMetaStruct(Map<String, Object> metaStruct) {
     for (Entry<String, Matcher<?>> entry : this.metaStructMatchers.entrySet()) {
       String key = entry.getKey();
       assertValue(
-          (Matcher<Object>) entry.getValue(), metaStruct.get(key), "Unexpected meta_struct '" + key + "'");
+          (Matcher<Object>) entry.getValue(),
+          metaStruct.get(key),
+          "Unexpected meta_struct '" + key + "'");
     }
   }
 }