From cec9d3b19de1f08d23def2bf6227d19ef878b67e Mon Sep 17 00:00:00 2001
From: Abdullah Alqahtani <61029571+anqorithm@users.noreply.github.com>
Date: Tue, 3 Nov 2026 11:08:06 +0100
Subject: [PATCH] test: verify shaded Jackson reads public Docker model
 annotations

---
 .circleci/config.yml                          |  2 +-
 core/build.gradle                             |  2 +-
 .../testcontainers/JarFileShadingTest.java    | 27 +++++++++++++++++++
 docs/index.md                                 |  2 ++
 4 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 262f7f3a2d5..4787d38b745 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -6,7 +6,7 @@ jobs:
     steps:
     - checkout
     - run:
-        command: ./gradlew --no-daemon --continue --scan testcontainers:test --tests '*GenericContainerRuleTest'
+        command: ./gradlew --no-daemon --continue --scan testcontainers:test --tests '*GenericContainerRuleTest' testcontainers:jarFileTest
     - run:
         name: Save test results
         command: |
diff --git a/core/build.gradle b/core/build.gradle
index d7a54a26afe..17992711cde 100644
--- a/core/build.gradle
+++ b/core/build.gradle
@@ -32,7 +32,7 @@ shadowJar {
 task jarFileTest(type: Test) {
     useJUnitPlatform()
     testClassesDirs = sourceSets.jarFileTest.output.classesDirs
-    classpath = sourceSets.jarFileTest.runtimeClasspath
+    classpath = sourceSets.jarFileTest.runtimeClasspath + configurations.runtimeClasspath
 
     inputs.files(shadowJar).withPathSensitivity(PathSensitivity.RELATIVE)
     systemProperty("jarFile", project.projectDir.toPath().relativize(shadowJar.outputs.files.singleFile.toPath()).toString())
diff --git a/core/src/jarFileTest/java/org/testcontainers/JarFileShadingTest.java b/core/src/jarFileTest/java/org/testcontainers/JarFileShadingTest.java
index 8b6f380f6eb..f54da988820 100644
--- a/core/src/jarFileTest/java/org/testcontainers/JarFileShadingTest.java
+++ b/core/src/jarFileTest/java/org/testcontainers/JarFileShadingTest.java
@@ -4,8 +4,11 @@
 import org.junit.jupiter.api.Test;
 
 import java.io.IOException;
+import java.net.URL;
+import java.net.URLClassLoader;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -38,6 +41,30 @@ void testMetaInfServices() throws Exception {
             .allMatch(it -> it.startsWith("org.testcontainers."));
     }
 
+    @Test
+    void testShadedMapperReadsPublicDockerModelAnnotations() throws Exception {
+        URL jar = Paths.get(System.getProperty("jarFile")).toUri().toURL();
+        try (URLClassLoader loader = new URLClassLoader(new URL[] { jar }, getClass().getClassLoader())) {
+            Class<?> config = loader.loadClass(
+                "org.testcontainers.shaded.com.github.dockerjava.core.DockerClientConfig"
+            );
+            Object mapper = config.getMethod("getDefaultObjectMapper").invoke(null);
+            Class<?> infoType = loader.loadClass("com.github.dockerjava.api.model.Info");
+            Object info = mapper
+                .getClass()
+                .getMethod("readValue", String.class, Class.class)
+                .invoke(
+                    mapper,
+                    "{\"ID\":\"docker-id\",\"Containers\":3,\"DockerRootDir\":\"/var/lib/docker\"}",
+                    infoType
+                );
+
+            assertThat(infoType.getMethod("getId").invoke(info)).isEqualTo("docker-id");
+            assertThat(infoType.getMethod("getContainers").invoke(info)).isEqualTo(3);
+            assertThat(infoType.getMethod("getDockerRootDir").invoke(info)).isEqualTo("/var/lib/docker");
+        }
+    }
+
     private ListAssert<String> assertThatFileList(Path path) throws IOException {
         return (ListAssert) assertThat(Files.list(path))
             .extracting(Path::getFileName)
diff --git a/docs/index.md b/docs/index.md
index 40304dd22ed..f9a09e58589 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -104,6 +104,8 @@ Using Gradle 5.0 or higher, you can add the following to the `dependencies` sect
     But there are also "private", implementation detail dependencies (e.g., docker-java-core, Guava, OkHttp, etc.) that are not exposed to public API but prone to conflicts with test code/application under test code. 
     As such, **these libraries are 'shaded' into the core Testcontainers JAR** and relocated under `org.testcontainers.shaded` to prevent class conflicts.
 
+    `jackson-annotations` is a transitive dependency of `docker-java-api` and is not shaded. If you manage Jackson versions, keep this artifact compatible with the Jackson version used by Testcontainers. Forcing an older version can cause linkage errors in the shaded mapper.
+
 ## Sponsors
 
 A huge thank you to our sponsors: