docs(showcase): add Javadoc and explanatory comments to T3 integration tests

Author: jinseopkim0

java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelT3MetricsExemplar.java

@@ -113,6 +113,8 @@ void tearDown() {
   // F3.1: HTTP M3 metric records T3 span as exemplar
   @Test
   void testHttpJson_m3ExemplarMatchesT3Span() throws Exception {
+    // Verifies that for HTTP/JSON, client request duration metrics attach exemplars
+    // pointing directly to the overall T3 operation span (traceId and spanId match).
     ApiTracerFactory compositeTracerFactory = createCompositeTracerFactory();
     EchoSettings settings = createEchoSettings(true);
     EchoStub stub = createStubWithServiceName(settings, compositeTracerFactory);
@@ -156,6 +158,8 @@ void testHttpJson_m3ExemplarMatchesT3Span() throws Exception {
   // F3.2: gRPC M3 metric records T3 span as exemplar
   @Test
   void testGrpc_m3ExemplarMatchesT3Span() throws Exception {
+    // Verifies that for gRPC, client request duration metrics attach exemplars
+    // pointing directly to the overall T3 operation span (traceId and spanId match).
     ApiTracerFactory compositeTracerFactory = createCompositeTracerFactory();
     EchoSettings settings = createEchoSettings(false);
     EchoStub stub = createStubWithServiceName(settings, compositeTracerFactory);
@@ -196,19 +200,37 @@ void testGrpc_m3ExemplarMatchesT3Span() throws Exception {
     }
   }
 
+  /**
+   * Creates a composite tracer factory combining both OpenTelemetry tracing and metrics factories.
+   *
+   * @return the configured {@link CompositeTracerFactory}
+   */
   private CompositeTracerFactory createCompositeTracerFactory() {
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     OpenTelemetryMetricsFactory metricsFactory = new OpenTelemetryMetricsFactory(openTelemetrySdk);
     return new CompositeTracerFactory(Arrays.asList(tracingFactory, metricsFactory));
   }
 
+  /**
+   * Waits until the in-memory span exporter records at least {@code minSpans} completed spans.
+   *
+   * @param minSpans the minimum number of spans expected
+   * @return the list of completed {@link SpanData} items
+   */
   private List<SpanData> waitAndCollectSpans(int minSpans) {
     Awaitility.await()
         .atMost(Duration.ofSeconds(5))
         .until(() -> spanExporter.getFinishedSpanItems().size() >= minSpans);
     return spanExporter.getFinishedSpanItems();
   }
 
+  /**
+   * Constructs {@link EchoSettings} configured for the local Showcase test server.
+   *
+   * @param isHttpJson {@code true} for HTTP/JSON transport; {@code false} for gRPC transport
+   * @return the configured {@link EchoSettings}
+   * @throws Exception if transport provider initialization fails
+   */
   private EchoSettings createEchoSettings(boolean isHttpJson) throws Exception {
     if (isHttpJson) {
       return EchoSettings.newHttpJsonBuilder()
@@ -231,6 +253,14 @@ private EchoSettings createEchoSettings(boolean isHttpJson) throws Exception {
     }
   }
 
+  /**
+   * Instantiates an {@link EchoStub} with custom service name and tracer factory.
+   *
+   * @param settings the client settings to base the stub on
+   * @param tracerFactory the tracer factory to register with the stub
+   * @return the initialized {@link EchoStub}
+   * @throws IOException if stub creation fails
+   */
   private EchoStub createStubWithServiceName(EchoSettings settings, ApiTracerFactory tracerFactory)
       throws IOException {
     EchoStubSettings.Builder builder =
@@ -239,7 +269,14 @@ private EchoStub createStubWithServiceName(EchoSettings settings, ApiTracerFacto
     return new ExtendedEchoStubSettings(builder).createStub();
   }
 
+  /** Extended {@link EchoStubSettings} that overrides {@link #getServiceName()} for testing. */
   private static class ExtendedEchoStubSettings extends EchoStubSettings {
+    /**
+     * Constructs settings wrapping the specified builder.
+     *
+     * @param builder the settings builder
+     * @throws IOException if base settings construction fails
+     */
     protected ExtendedEchoStubSettings(EchoStubSettings.Builder builder) throws IOException {
       super(builder);
     }

java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelT3T4Hierarchy.java

@@ -113,6 +113,12 @@ void tearDown() {
   // F2.1: HTTP T3/T4 retry succeeds (1 T3 span, 2 T4 child spans)
   @Test
   void testHttpJson_retrySucceeds() throws Exception {
+    // Verifies HTTP/JSON retry behavior: transient failure on attempt 0 is retried and succeeds on
+    // attempt 1.
+    // Asserts:
+    // 1. Exactly one overall INTERNAL operation span (T3).
+    // 2. Both attempt spans (T4) have parent_span_id == T3.span_id.
+    // 3. T3 operation span aggregates the successful status (OK) and 200 HTTP code.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
 
     // Sequence: attempt 1 -> UNAVAILABLE, attempt 2 -> OK
@@ -203,6 +209,11 @@ void testHttpJson_retrySucceeds() throws Exception {
   // F2.2: HTTP T3/T4 retries exhausted
   @Test
   void testHttpJson_retriesExhausted() throws Exception {
+    // Verifies HTTP/JSON behavior when retries are exhausted after repeated failures.
+    // Asserts:
+    // 1. Exactly one overall INTERNAL operation span (T3).
+    // 2. All attempt spans (T4) are linked to the T3 span as parent.
+    // 3. T3 operation span aggregates ERROR status, 503 HTTP status, and UNAVAILABLE RPC status.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
 
     // Sequence: 3 UNAVAILABLE responses
@@ -300,6 +311,12 @@ void testHttpJson_retriesExhausted() throws Exception {
   // F2.3: gRPC T3/T4 retry succeeds
   @Test
   void testGrpc_retrySucceeds() throws Exception {
+    // Verifies gRPC retry behavior: transient failure on attempt 0 is retried and succeeds on
+    // attempt 1.
+    // Asserts:
+    // 1. Exactly one overall INTERNAL operation span (T3).
+    // 2. Both attempt spans (T4) have parent_span_id == T3.span_id.
+    // 3. T3 operation span aggregates the successful status (OK).
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
 
     // Sequence: attempt 1 -> UNAVAILABLE, attempt 2 -> OK
@@ -378,6 +395,11 @@ void testGrpc_retrySucceeds() throws Exception {
   // F2.4: gRPC T3/T4 retries exhausted
   @Test
   void testGrpc_retriesExhausted() throws Exception {
+    // Verifies gRPC behavior when retries are exhausted after repeated failures.
+    // Asserts:
+    // 1. Exactly one overall INTERNAL operation span (T3).
+    // 2. All attempt spans (T4) are linked to the T3 span as parent.
+    // 3. T3 operation span aggregates ERROR status and UNAVAILABLE RPC status.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
 
     // Sequence: 3 UNAVAILABLE responses
@@ -466,13 +488,29 @@ void testGrpc_retriesExhausted() throws Exception {
     }
   }
 
+  /**
+   * Waits until the in-memory span exporter records at least {@code minSpans} completed spans.
+   *
+   * @param minSpans the minimum number of spans expected
+   * @return the list of completed {@link SpanData} items
+   */
   private List<SpanData> waitAndCollectSpans(int minSpans) {
     Awaitility.await()
         .atMost(Duration.ofSeconds(5))
         .until(() -> spanExporter.getFinishedSpanItems().size() >= minSpans);
     return spanExporter.getFinishedSpanItems();
   }
 
+  /**
+   * Constructs a {@link SequenceServiceClient} configured with custom retry settings and tracing.
+   *
+   * @param isHttpJson {@code true} for HTTP/JSON transport; {@code false} for gRPC transport
+   * @param tracingFactory the tracer factory to register with the client
+   * @param retrySettings the custom retry settings to apply to attemptSequence
+   * @param retryableCodes the set of status codes considered retryable
+   * @return the configured {@link SequenceServiceClient}
+   * @throws Exception if client initialization fails
+   */
   private SequenceServiceClient createSequenceClient(
       boolean isHttpJson,
       OpenTelemetryTracingFactory tracingFactory,
@@ -514,7 +552,17 @@ private SequenceServiceClient createSequenceClient(
         new ExtendedSequenceServiceStubSettings(stubSettingsBuilder).createStub());
   }
 
+  /**
+   * Extended {@link SequenceServiceStubSettings} that overrides {@link #getServiceName()} for
+   * testing.
+   */
   private static class ExtendedSequenceServiceStubSettings extends SequenceServiceStubSettings {
+    /**
+     * Constructs settings wrapping the specified builder.
+     *
+     * @param builder the settings builder
+     * @throws IOException if base settings construction fails
+     */
     protected ExtendedSequenceServiceStubSettings(SequenceServiceStubSettings.Builder builder)
         throws IOException {
       super(builder);

java-showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITOtelT3Tracing.java

@@ -97,6 +97,8 @@ void tearDown() {
   // F1.1: HTTP no traces emitted unless enabled.
   @Test
   void testTracingDisabled_httpjson() throws Exception {
+    // Verifies that when OpenTelemetry tracing is not configured on the client settings,
+    // no spans are recorded for HTTP/JSON calls.
     EchoSettings settings = createEchoSettings(true);
     try (EchoClient client = EchoClient.create(settings)) {
       client.echo(EchoRequest.newBuilder().setContent("test-f1-1").build());
@@ -108,6 +110,10 @@ void testTracingDisabled_httpjson() throws Exception {
   // F1.2: HTTP T3 success case name and attributes conform to requirements.
   @Test
   void testT3Success_httpjson() throws Exception {
+    // Verifies that a successful HTTP/JSON call produces a T3 INTERNAL span with proper
+    // semantic convention attributes (http rpc.system, server.address, server.port, 200
+    // http.response.status_code,
+    // url.template) and UNSET status.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(true);
     EchoStub stub = createStubWithServiceName(settings, tracingFactory);
@@ -170,6 +176,8 @@ void testT3Success_httpjson() throws Exception {
   // F1.3: HTTP T3 server failures case name and attributes conform to requirements.
   @Test
   void testT3ServerFailure_httpjson() throws Exception {
+    // Verifies that a server-side error on HTTP/JSON produces a T3 INTERNAL span with ERROR status,
+    // 400 http.response.status_code, and error.type.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(true);
     EchoStub stub = createStubWithServiceName(settings, tracingFactory);
@@ -218,6 +226,9 @@ void testT3ServerFailure_httpjson() throws Exception {
   // F1.4: HTTP T3 client failures case name and attributes conform to requirements.
   @Test
   void testT3ClientFailure_httpjson() throws Exception {
+    // Verifies that a client-side timeout on HTTP/JSON produces a T3 INTERNAL span with ERROR
+    // status,
+    // 504 http.response.status_code, and error.type.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(true);
     // Configure 1000ms timeout for blockCallable
@@ -269,6 +280,8 @@ void testT3ClientFailure_httpjson() throws Exception {
   // F1.5: gRPC no traces emitted unless enabled.
   @Test
   void testTracingDisabled_grpc() throws Exception {
+    // Verifies that when OpenTelemetry tracing is not configured on the client settings,
+    // no spans are recorded for gRPC calls.
     EchoSettings settings = createEchoSettings(false);
     try (EchoClient client = EchoClient.create(settings)) {
       client.echo(EchoRequest.newBuilder().setContent("test-f1-5").build());
@@ -280,6 +293,10 @@ void testTracingDisabled_grpc() throws Exception {
   // F1.6: gRPC T3 success case name and attributes conform to requirements.
   @Test
   void testT3Success_grpc() throws Exception {
+    // Verifies that a successful gRPC call produces a T3 INTERNAL span with proper
+    // semantic convention attributes (grpc rpc.system, server.address, server.port, OK
+    // rpc.response.status_code)
+    // and UNSET status.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(false);
     EchoStub stub = createStubWithServiceName(settings, tracingFactory);
@@ -338,6 +355,8 @@ void testT3Success_grpc() throws Exception {
   // F1.7: gRPC T3 server failures case name and attributes conform to requirements.
   @Test
   void testT3ServerFailure_grpc() throws Exception {
+    // Verifies that a server-side error on gRPC produces a T3 INTERNAL span with ERROR status,
+    // INVALID_ARGUMENT rpc.response.status_code, and error.type.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(false);
     EchoStub stub = createStubWithServiceName(settings, tracingFactory);
@@ -387,6 +406,8 @@ void testT3ServerFailure_grpc() throws Exception {
   // F1.8: gRPC T3 client failures case name and attributes conform to requirements.
   @Test
   void testT3ClientFailure_grpc() throws Exception {
+    // Verifies that a client-side timeout on gRPC produces a T3 INTERNAL span with ERROR status,
+    // DEADLINE_EXCEEDED rpc.response.status_code, and error.type.
     OpenTelemetryTracingFactory tracingFactory = new OpenTelemetryTracingFactory(openTelemetrySdk);
     EchoSettings settings = createEchoSettings(false);
     // Configure 1000ms timeout for blockCallable
@@ -435,13 +456,26 @@ void testT3ClientFailure_grpc() throws Exception {
     }
   }
 
+  /**
+   * Waits until the in-memory span exporter records at least {@code minSpans} completed spans.
+   *
+   * @param minSpans the minimum number of spans expected
+   * @return the list of completed {@link SpanData} items
+   */
   private List<SpanData> waitAndCollectSpans(int minSpans) {
     Awaitility.await()
         .atMost(Duration.ofSeconds(5))
         .until(() -> spanExporter.getFinishedSpanItems().size() >= minSpans);
     return spanExporter.getFinishedSpanItems();
   }
 
+  /**
+   * Constructs {@link EchoSettings} configured for the local Showcase test server.
+   *
+   * @param isHttpJson {@code true} for HTTP/JSON transport; {@code false} for gRPC transport
+   * @return the configured {@link EchoSettings}
+   * @throws Exception if transport provider initialization fails
+   */
   private EchoSettings createEchoSettings(boolean isHttpJson) throws Exception {
     if (isHttpJson) {
       return EchoSettings.newHttpJsonBuilder()
@@ -464,6 +498,14 @@ private EchoSettings createEchoSettings(boolean isHttpJson) throws Exception {
     }
   }
 
+  /**
+   * Instantiates an {@link EchoStub} with custom service name and tracer factory.
+   *
+   * @param settings the client settings to base the stub on
+   * @param tracingFactory the tracer factory to register with the stub
+   * @return the initialized {@link EchoStub}
+   * @throws IOException if stub creation fails
+   */
   private EchoStub createStubWithServiceName(
       EchoSettings settings, OpenTelemetryTracingFactory tracingFactory) throws IOException {
     EchoStubSettings.Builder builder =
@@ -472,7 +514,14 @@ private EchoStub createStubWithServiceName(
     return new ExtendedEchoStubSettings(builder).createStub();
   }
 
+  /** Extended {@link EchoStubSettings} that overrides {@link #getServiceName()} for testing. */
   private static class ExtendedEchoStubSettings extends EchoStubSettings {
+    /**
+     * Constructs settings wrapping the specified builder.
+     *
+     * @param builder the settings builder
+     * @throws IOException if base settings construction fails
+     */
     protected ExtendedEchoStubSettings(EchoStubSettings.Builder builder) throws IOException {
       super(builder);
     }