Track Testcontainers images as Gradle test inputs

[bric3]

What Does This Do

Introduces an opt-in dd-trace-java.testcontainers plugin that model docker images as dependencies, allowing to track their digest as task input.

import datadog.buildlogic.testcontainers.image

plugins {
  id("dd-trace-java.testcontainers")
}

dependencies {
  testContainerImage(image("cassandra:4", "test.cassandra.image"))
}

Each declaration associates an image with a system property used by the test. Before Gradle evaluates the test task’s cache inputs, the plugin resolves the effective image to an immutable digest and passes that value under the system property.

The test need to be written using the constructor accepting DockerImageName, e.g. :

CassandraContainer container = new CassandraContainer(
    DockerImageName.parse(System.getProperty("test.cassandra.image"))
        .asCompatibleSubstituteFor("cassandra"));

Where, test.cassandra.image wll have a value like that registry-1.docker.io/library/cassandra@sha256:b9451ebdfa53f9e22b470e1420f2a94a3433738b7f25350472d3443f0b203b75.

This PR adopts the plugin in the existing usage.

Motivation

Using Test Container constructors like new CassandraContainer("cassandra:4"), or new GenericContainer("icr.io/appcafe/websphere-traditional:latest"). Indeed, mutable image tag can change without any change to test sources or Java dependencies, thus defeating the Gradle fingerprinting.

Resolving the tag on every invocation means an unchanged digest allow to safely reuse build-cache results, before it wasn't guranteed.

Additional Notes

Our test suite relied on a feature of Test Container that allowed to change the image name prefix, this mechanism need to be handled at the plugin level now. As such Docker Hub is used locally, while CI the defines a TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX and will instead resolve the image to registry.ddbuild.io/images/mirror/cassandra@sha256:b9451ebdfa53f9e22b470e1420f2a94a3433738b7f25350472d3443f0b203b75.

Note that implicit Testcontainers helper images are not tracked as they are not explicitly declared.

This related to #12604

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors
• Once approved, use merge queue to merge the PR

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.05 s	13.97 s	[-0.3%; +1.5%] (no difference)
startup:insecure-bank:tracing:Agent	12.94 s	12.98 s	[-0.9%; +0.3%] (no difference)
startup:petclinic:appsec:Agent	16.49 s	16.85 s	[-6.4%; +2.2%] (no difference)
startup:petclinic:iast:Agent	17.02 s	17.07 s	[-1.0%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	16.02 s	16.89 s	[-9.3%; -0.9%] (maybe better)
startup:petclinic:sca:Agent	17.00 s	16.76 s	[+0.4%; +2.4%] (maybe worse)
startup:petclinic:tracing:Agent	16.15 s	16.12 s	[-0.9%; +1.2%] (no difference)

Commit: 7db6d24e · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-24T19:32:11.035324Z	940c875	Draft marked ready
🔒 Security Review	✅ Completed 2026-09-24T19:28:16.340767Z	940c875	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 940c875f0b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[datadog-prod-us1-6]

Two independent test-configuration issues were found: Redis container tests fail in CI because mirrored images are not declared as compatible substitutes, and the WebSphere smoke test now runs only on Java 25, dropping the established Java 8 coverage.

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit 940c875 · @DataDog review to ask questions}

[sarahchen6]

Did a review with Codex and it left one comment that could use a look:

P2 — Track the shared test-agent container image too. TestAgentBackend.defaultImage()
constructs the mutable v1.64.1 tag at TestAgentBackend.java:108, which is passed
directly to Testcontainers at TestAgentBackend.java:136 and exercised by
TestAgentBackendContainerTest.java:46. Since dd-smoke-tests/build.gradle:3 does not
apply the new plugin, a moved tag can still reuse stale :dd-smoke-tests:test results.
Could this image also be declared through the plugin and consumed via its resolved
system property?

[sarahchen6]

IIUC the goal of this PR is to ensure the Gradle cache considers the Testcontainers images when deciding whether or not the cache can be reused ? The new plugin resolves the declared image tag and registers this freshly-resolved image as a Gradle task input. Then the cache is only used if the images are the same, preventing running tests with outdated images.

This otherwise seems reasonable to me!

[amarziali]

looks good. I've added an idea (that can be discarded or addressed later if useful)

[bric3]

/merge

[gh-worker-devflow-routing-ef8351]

View all feedbacks in Devflow UI.

2026-09-25 14:02:20 UTC ℹ️ Start processing command /merge

---

2026-09-25 14:02:30 UTC ℹ️ MergeQueue: Pull request is not mergeable yet

It will be processed automatically as soon as GitHub reports it as mergeable. View in MergeQueue UI.

• Run /code blockers to see what is blocking it.
• Run /remove to cancel it.

---

2026-09-25 14:29:16 UTC ℹ️ MergeQueue: merge request added to the queue

The expected merge time in master is approximately 1h (p90).

---

2026-09-25 15:28:46 UTC ℹ️ MergeQueue: This merge request was merged