Add testLatestDeps() helper method

Author: trask

.github/agents/knowledge/general-rules.md

@@ -27,6 +27,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Semconv | Dual semconv testing | `SemconvStability`, `maybeStable`, semconv Gradle tasks | `testing-semconv-stability.md` |
 | Testing | General test patterns | Test files in scope — assertion style, test method signatures and throws clauses, resource cleanup, attribute assertions | `testing-general-patterns.md` |
 | Testing | Experimental flag tests | `testExperimental`, experimental attribute assertions, `experimental` flags in JVM args or system properties | `testing-experimental-flags.md` |
+| Testing | Flag-gated / mode-dependent assertion shape (experimental, `testLatestDeps`, semconv) — hoist flag into per-class constant, inline ternary, `if` for structural differences | Test classes branching on `EXPERIMENTAL_ATTRIBUTES`, `Boolean.getBoolean("testLatestDeps")`, or `emitOld*`/`emitStable*` | `testing-general-patterns.md` |
 | Library | TelemetryBuilder/getter/setter patterns | Library instrumentation classes | `library-patterns.md` |
 | API | Deprecation and breaking-change policy | Public API changes | `api-deprecation-policy.md` |
 | Config | Config property stability/renames/removals | `otel.instrumentation.*` property changes, `DeclarativeConfigUtil` or `ConfigProperties` usage | `config-property-stability.md` |

.github/agents/knowledge/testing-experimental-flags.md

@@ -51,30 +51,44 @@ val testExperimental by registering(Test::class) {
 
 ## Java Test Patterns
 
-Read the flag once into a `private static final boolean` at class level:
+For the cross-cutting shape — inline ternary with `null` for "absent", when to use top-level
+`if` blocks, and `assumeTrue(...)` guidance — see
+[testing-general-patterns.md](testing-general-patterns.md#flag-gated--mode-dependent-assertions).
+The experimental-specific patterns below build on that shape.
+
+### Hoist the flag into a per-class `EXPERIMENTAL_ATTRIBUTES` constant
+
+Unlike `testLatestDeps()` / `emitStable*Semconv()`, there is no shared helper for
+experimental flags — the property name is module-specific. Read it once into a
+`private static final boolean` near the top of the class and reference the constant
+everywhere in the file:
 
 ```java
 private static final boolean EXPERIMENTAL_ATTRIBUTES =
     Boolean.getBoolean("otel.instrumentation.<module>.experimental-span-attributes");
 ```
 
-Use inline ternary in assertions — `null` means attribute expected absent:
+When multiple experimental flags coexist in one class, use a more specific name per flag.
+Replace every in-file occurrence of the raw `Boolean.getBoolean("…")` call with the
+constant — including plain `if`, `&&`, and `assumeTrue(...)`, not just inside ternaries.
 
-```java
-equalTo(ExperimentalAttributes.SOME_ATTR, EXPERIMENTAL_ATTRIBUTES ? "value" : null)
-```
+### Single-arg `experimental(value)` helper
 
-When many assertions share the flag, extract an `experimental()` helper:
+Experimental attributes are by definition absent when the flag is off, so the off-branch is
+always `null`. When several assertions in the same class gate attributes on
+`EXPERIMENTAL_ATTRIBUTES`, extract a tiny helper:
 
 ```java
 @Nullable
 private static <T> T experimental(T value) {
   return EXPERIMENTAL_ATTRIBUTES ? value : null;
 }
+
+equalTo(SOME_KEY, experimental("value"))
 ```
 
 For multiple test classes sharing the same flag, move the helper into a shared
 `ExperimentalTestHelper` class and static-import it.
 
-Use `assumeTrue(EXPERIMENTAL_ATTRIBUTES)` only when an entire test is meaningful in
-experimental mode only — prefer the ternary/helper pattern so both modes are exercised.
+Do **not** add a two-argument `experimental(on, off)` helper — for the rare case where the
+off-branch is non-null, an inline ternary is more readable.

.github/agents/knowledge/testing-general-patterns.md

@@ -130,3 +130,82 @@ unless the span ordering within a trace is genuinely non-deterministic (e.g., co
 producers/consumers, thread-pool fan-out, or channel interleaving). Sequential operations
 like `repeat {}` loops, single-child traces, and `flux` sequential emission produce spans
 in deterministic order — use `hasSpansSatisfyingExactly` for those.
+
+## Flag-Gated / Mode-Dependent Assertions
+
+Several test modes change which attributes, span names, status codes, or span indexes are
+expected:
+
+- Experimental attributes (`-Dotel.instrumentation.<module>.experimental-*=true`) — see
+  [testing-experimental-flags.md](testing-experimental-flags.md).
+- Semconv stability (`-Dotel.semconv-stability.opt-in=...`) — see
+  [testing-semconv-stability.md](testing-semconv-stability.md).
+- `testLatestDeps` Gradle property — runs against the newest supported library versions
+  instead of the pinned earliest-supported ones.
+
+The subsections below cover the cross-cutting *shape* rules. Flag-specific tooling
+(helpers, constants, `/dup` handling) lives in the per-flag docs linked above.
+
+### Read the flag through a shared static helper, not a per-class field
+
+Each flag has a shared static accessor; static-import it and call it directly. Never call
+`Boolean.getBoolean("…")` inline, never duplicate the property-name string at the call
+site, and replace any per-class `TEST_LATEST_DEPS` constant with the shared accessor —
+including in plain `if`, `&&`, and `assumeTrue(...)`, not just inside ternaries.
+
+```java
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
+import static io.opentelemetry.instrumentation.api.internal.SemconvStability.emitStableDatabaseSemconv;
+
+// …
+
+.hasName(testLatestDeps() ? "GET" : "HTTP GET")
+equalTo(DB_USER, emitStableDatabaseSemconv() ? null : USER_DB)
+```
+
+| Flag | Shared accessor | Where it lives |
+| --- | --- | --- |
+| `-PtestLatestDeps=true` | `testLatestDeps()` | `io.opentelemetry.instrumentation.testing.util.TestLatestDeps` (testing-common) |
+| `otel.semconv-stability.opt-in=…` | `emitStableDatabaseSemconv()`, `emitOldDatabaseSemconv()`, `emitStableCodeSemconv()`, etc. | `io.opentelemetry.instrumentation.api.internal.SemconvStability` |
+| `otel.instrumentation.<module>.experimental-*` | per-module `EXPERIMENTAL_ATTRIBUTES` constant — see [testing-experimental-flags.md](testing-experimental-flags.md) | within the test class |
+
+### Inline ternary in `equalTo(...)` with `null` for "absent"
+
+Push the ternary as deep as possible — into the `equalTo` value or single attribute key —
+rather than duplicating two whole `hasAttributesSatisfyingExactly(...)` blocks under a
+`flag ? a : b`. The assertion API treats `null` as "expect attribute absent":
+
+```java
+equalTo(DB_USER, emitStableDatabaseSemconv() ? null : USER_DB)
+equalTo(ERROR_TYPE, emitStableDatabaseSemconv() ? "42601" : null)
+equalTo(SOME_KEY, EXPERIMENTAL_ATTRIBUTES ? "value" : null)
+span.hasName(testLatestDeps() ? "GET" : "HTTP GET")
+.hasParent(trace.getSpan(testLatestDeps() ? 0 : 1))
+```
+
+Do **not** introduce two-argument `flag(on, off)` helpers — the inline ternary is more
+readable. The only single-arg helper is `experimental(value)`, which only works because
+its off-branch is always `null` (see
+[testing-experimental-flags.md](testing-experimental-flags.md)).
+
+### Use `if` (not `if/else`) when structure differs
+
+When the *set* of attributes (count, keys) — not just values — differs between modes, use
+top-level `if` blocks rather than a ternary swapping the entire assertion list. For semconv
+this is **mandatory**: `/dup` mode must execute both branches, so never use `if/else` —
+see [testing-semconv-stability.md](testing-semconv-stability.md) for details.
+
+```java
+if (emitStableCodeSemconv()) {
+  assertThat(attributes).containsEntry(CODE_FUNCTION_NAME, "MyClass.myMethod");
+}
+if (emitOldCodeSemconv()) {
+  assertThat(attributes).containsEntry(CODE_NAMESPACE, "MyClass");
+}
+```
+
+### `assumeTrue(...)` only when one mode is meaningless
+
+Use `assumeTrue(EXPERIMENTAL_ATTRIBUTES)` / `assumeTrue(emitStable*())` /
+`assumeTrue(testLatestDeps())` only when an entire test is meaningful in one mode only —
+prefer the ternary/`if` pattern so both modes are exercised.

.github/agents/knowledge/testing-semconv-stability.md

@@ -76,26 +76,38 @@ for other domains `check { dependsOn(testStableSemconv) }`.
 
 ## Asserting Attributes in Tests
 
-Preferred approach (most compact) — inline ternary with `emitStable*()`, where `null` means
-the attribute is expected absent:
+For the cross-cutting shape — inline ternary with `null` for "absent", static-imported flag
+accessors, and `assumeTrue(...)` guidance — see
+[testing-general-patterns.md](testing-general-patterns.md#flag-gated--mode-dependent-assertions).
+The semconv-specific patterns below build on that shape.
 
-```java
-equalTo(DB_USER, emitStableDatabaseSemconv() ? null : USER_DB)
-equalTo(ERROR_TYPE, emitStableDatabaseSemconv() ? "42601" : null)
-span.hasName(emitStableDatabaseSemconv() ? "SELECT" : "SELECT dbname")
-```
+### Import `emitStable*Semconv()` directly
+
+Static-import `emitStable*Semconv()` / `emitOld*Semconv()` from
+`io.opentelemetry.instrumentation.api.internal.SemconvStability` and call them inline. Do
+**not** wrap them in a per-class `static final boolean` field — they are already cheap
+static accessors.
 
-Use `maybeStable(oldKey)` when only the attribute key changes and the value stays the same.
-`maybeStable()` does NOT cover `dup` mode — use separate `if` blocks for that.
+### `maybeStable(OLD_KEY)` for 1:1 key renames
+
+Use `maybeStable(OLD_KEY)` when only the attribute *key* flips between old and stable
+semconv and the value is identical:
 
 ```java
 span.hasAttribute(equalTo(maybeStable(DB_STATEMENT), "SELECT ?"));
 ```
 
-Use separate `if` blocks (not `if/else`) when assertion structure differs significantly between
-modes — this ensures both branches execute in `dup` mode:
+`maybeStable()` does **not** cover `/dup` mode (it returns one key, not both), and does
+**not** apply where the mapping isn't 1:1 — for example `DB_RESPONSE_STATUS_CODE` →
+`ERROR_TYPE`. Use `emitOld*()` / `emitStable*()` `if` blocks for those.
+
+### `if` blocks (never `if/else`) for `/dup` mode
+
+`/dup` mode emits **both** old and stable attributes, so each must be asserted in an
+independent top-level `if` block. Never use `if/else`:
 
 ```java
+// CORRECT — both branches run in /dup mode
 if (emitStableCodeSemconv()) {
   assertThat(attributes).containsEntry(CODE_FUNCTION_NAME, "MyClass.myMethod");
 }
@@ -104,7 +116,9 @@ if (emitOldCodeSemconv()) {
 }
 ```
 
-Use `assumeTrue(emitStable*())` only when an entire test is meaningful in one mode only.
+Do **not** add a single-arg `stable(value)` / `old(value)` helper — both modes typically
+emit real values (not `null`), and `maybeStable(...)` already covers the 1:1 key-rename
+case.
 
 ## Key Rules
 

conventions/src/main/kotlin/io/opentelemetry/instrumentation/gradle/StaticImportFormatter.kt

@@ -77,6 +77,11 @@ class StaticImportFormatter : FormatterFunc.NeedsFile, Serializable {
         "io.opentelemetry.instrumentation.api.internal.SemconvStability",
         "emit[a-zA-Z0-9]*",
       ),
+      Rule(
+        "TestLatestDeps",
+        "io.opentelemetry.instrumentation.testing.util.TestLatestDeps",
+        "testLatestDeps",
+      ),
       Rule(
         "SqlDialect",
         "io.opentelemetry.instrumentation.api.incubator.semconv.db.SqlDialect",

instrumentation/apache-dubbo-2.7/library-autoconfigure/src/test/java/io/opentelemetry/instrumentation/apachedubbo/v2_7/DubboHeadersGetterTest.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.instrumentation.apachedubbo.v2_7;
 
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
 import static java.util.Collections.singletonMap;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.when;
@@ -32,7 +33,7 @@ void testKeys() throws ReflectiveOperationException {
     when(context.getLocalAddress()).thenReturn(new InetSocketAddress(1));
 
     // for latest dep tests call getObjectAttachments, otherwise call getAttachments
-    if (Boolean.getBoolean("testLatestDeps")) {
+    if (testLatestDeps()) {
       when(getObjectAttachments()).thenReturn(singletonMap("key", "value"));
     } else {
       when(rpcInvocation.getAttachments()).thenReturn(singletonMap("key", "value"));

instrumentation/apache-dubbo-2.7/testing/src/main/java/io/opentelemetry/instrumentation/apachedubbo/v2_7/AbstractDubboTest.java

@@ -9,6 +9,7 @@
 import static io.opentelemetry.instrumentation.api.internal.SemconvStability.emitStableRpcSemconv;
 import static io.opentelemetry.instrumentation.testing.GlobalTraceUtil.runWithSpan;
 import static io.opentelemetry.instrumentation.testing.junit.service.SemconvServiceStabilityUtil.maybeStablePeerService;
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.equalTo;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.satisfies;
@@ -186,7 +187,7 @@ void testApacheDubboBase() throws ReflectiveOperationException {
                                         : "hello"),
                                 equalTo(
                                     maybeStablePeerService(),
-                                    hasServicePeerName() && Boolean.getBoolean("testLatestDeps")
+                                    hasServicePeerName() && testLatestDeps()
                                         ? "test-peer-service"
                                         : null),
                                 satisfies(
@@ -370,7 +371,7 @@ void testApacheDubboTest() throws ReflectiveOperationException {
                                         : "hello"),
                                 equalTo(
                                     maybeStablePeerService(),
-                                    hasServicePeerName() && Boolean.getBoolean("testLatestDeps")
+                                    hasServicePeerName() && testLatestDeps()
                                         ? "test-peer-service"
                                         : null),
                                 satisfies(
@@ -484,7 +485,7 @@ static void assertNetworkType(AbstractStringAssert<?> stringAssert) {
 
   static void assertLatestDeps(
       AbstractAssert<?, ?> assertion, Consumer<AbstractAssert<?, ?>> action) {
-    if (Boolean.getBoolean("testLatestDeps")) {
+    if (testLatestDeps()) {
       action.accept(assertion);
     } else {
       assertion.isNull();

instrumentation/apache-dubbo-2.7/testing/src/main/java/io/opentelemetry/instrumentation/apachedubbo/v2_7/AbstractDubboTraceChainTest.java

@@ -10,6 +10,7 @@
 import static io.opentelemetry.instrumentation.api.internal.SemconvStability.emitStableRpcSemconv;
 import static io.opentelemetry.instrumentation.testing.GlobalTraceUtil.runWithSpan;
 import static io.opentelemetry.instrumentation.testing.junit.service.SemconvServiceStabilityUtil.maybeStablePeerService;
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.equalTo;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.satisfies;
@@ -229,7 +230,7 @@ void testDubboChain() throws ReflectiveOperationException {
                                         : "hello"),
                                 equalTo(
                                     maybeStablePeerService(),
-                                    hasServicePeerName() && Boolean.getBoolean("testLatestDeps")
+                                    hasServicePeerName() && testLatestDeps()
                                         ? "test-peer-service"
                                         : null),
                                 satisfies(
@@ -285,7 +286,7 @@ void testDubboChain() throws ReflectiveOperationException {
                                         : "hello"),
                                 equalTo(
                                     maybeStablePeerService(),
-                                    hasServicePeerName() && Boolean.getBoolean("testLatestDeps")
+                                    hasServicePeerName() && testLatestDeps()
                                         ? "test-peer-service"
                                         : null),
                                 satisfies(
@@ -510,7 +511,7 @@ void testDubboChainInJvm() throws ReflectiveOperationException {
                                         : "hello"),
                                 equalTo(
                                     maybeStablePeerService(),
-                                    hasServicePeerName() && Boolean.getBoolean("testLatestDeps")
+                                    hasServicePeerName() && testLatestDeps()
                                         ? "test-peer-service"
                                         : null),
                                 satisfies(

instrumentation/apache-httpclient/apache-httpclient-5.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/apachehttpclient/v5_0/ApacheHttpClientTest.java

@@ -7,6 +7,7 @@
 
 import static io.opentelemetry.instrumentation.testing.junit.http.AbstractHttpClientTest.CONNECTION_TIMEOUT;
 import static io.opentelemetry.instrumentation.testing.junit.http.AbstractHttpClientTest.READ_TIMEOUT;
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
 
 import io.opentelemetry.instrumentation.testing.junit.InstrumentationExtension;
 import io.opentelemetry.instrumentation.testing.junit.http.HttpClientInstrumentationExtension;
@@ -224,7 +225,7 @@ protected void configure(HttpClientTestOptions.Builder optionsBuilder) {
       // apparently apache http client does not report the 302 status code?
       optionsBuilder.setResponseCodeOnRedirectError(null);
 
-      if (Boolean.getBoolean("testLatestDeps")) {
+      if (testLatestDeps()) {
         optionsBuilder.disableTestHttps();
         optionsBuilder.disableTestRemoteConnection();
       }

instrumentation/armeria/armeria-1.3/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/armeria/v1_3/ArmeriaHttpServerTest.java

@@ -5,6 +5,8 @@
 
 package io.opentelemetry.javaagent.instrumentation.armeria.v1_3;
 
+import static io.opentelemetry.instrumentation.testing.util.TestLatestDeps.testLatestDeps;
+
 import com.linecorp.armeria.server.ServerBuilder;
 import io.opentelemetry.instrumentation.armeria.v1_3.AbstractArmeriaHttpServerTest;
 import io.opentelemetry.instrumentation.testing.junit.InstrumentationExtension;
@@ -31,7 +33,7 @@ protected void configure(HttpServerTestOptions options) {
     options.setTestHttpPipelining(false);
     // span for non-standard request is created by netty instrumentation when not running latest
     // dep tests
-    if (Boolean.getBoolean("testLatestDeps")) {
+    if (testLatestDeps()) {
       options.disableTestNonStandardHttpMethod();
     } else {
       options.setResponseCodeOnNonStandardHttpMethod(405);