From e234de203d7f8e546f8d8bf1ede8747ba577681c Mon Sep 17 00:00:00 2001
From: Hyun Lee <dlwhdugs4147@gmail.com>
Date: Mon, 21 Sep 2026 18:13:26 -0500
Subject: [PATCH] Expose explicitly declared image compatibility

Allow container modules to distinguish an explicit compatibility declaration from compatibility inferred from the image name, without changing validation behavior.

Signed-off-by: Hyun Lee <dlwhdugs4147@gmail.com>
---
 .../utility/DockerImageName.java              | 11 +++++++
 .../DockerImageNameCompatibilityTest.java     | 31 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/core/src/main/java/org/testcontainers/utility/DockerImageName.java b/core/src/main/java/org/testcontainers/utility/DockerImageName.java
index b3babc29c91..145e7f7a715 100644
--- a/core/src/main/java/org/testcontainers/utility/DockerImageName.java
+++ b/core/src/main/java/org/testcontainers/utility/DockerImageName.java
@@ -252,6 +252,17 @@ public DockerImageName asCompatibleSubstituteFor(DockerImageName otherImageName)
         return withCompatibleSubstituteFor(otherImageName);
     }
 
+    /**
+     * Returns the image explicitly declared as compatible through {@link #asCompatibleSubstituteFor(DockerImageName)}
+     * or {@link #asCompatibleSubstituteFor(String)}. This does not infer compatibility from the image name.
+     *
+     * @return the declared compatible image, or {@code null} if no compatibility has been declared
+     */
+    @Nullable
+    public DockerImageName getCompatibleSubstituteFor() {
+        return compatibleSubstituteFor;
+    }
+
     /**
      * Test whether this {@link DockerImageName} has declared compatibility with another image (set using
      * {@link DockerImageName#asCompatibleSubstituteFor(String)} or
diff --git a/core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java b/core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java
index ce0759fec47..2b4cc7cc8b9 100644
--- a/core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java
+++ b/core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java
@@ -7,6 +7,37 @@
 
 class DockerImageNameCompatibilityTest {
 
+    @Test
+    void testNoExplicitCompatibility() {
+        DockerImageName image = DockerImageName.parse("wiremock/wiremock:test");
+
+        assertThat(image.isCompatibleWith(DockerImageName.parse("wiremock/wiremock"))).isTrue();
+        assertThat(image.getCompatibleSubstituteFor()).isNull();
+    }
+
+    @Test
+    void testExplicitCompatibilityFromString() {
+        DockerImageName original = DockerImageName.parse("custom/wiremock:test");
+        DockerImageName image = original.asCompatibleSubstituteFor("wiremock/wiremock:3.0.0");
+
+        assertThat(image.getCompatibleSubstituteFor()).isEqualTo(DockerImageName.parse("wiremock/wiremock:3.0.0"));
+        assertThat(original.getCompatibleSubstituteFor()).isNull();
+    }
+
+    @Test
+    void testExplicitCompatibilitySurvivesImageChanges() {
+        DockerImageName compatibleImage = DockerImageName.parse("wiremock/wiremock:3.0.0");
+        DockerImageName image = DockerImageName
+            .parse("custom/wiremock:test")
+            .asCompatibleSubstituteFor(compatibleImage)
+            .withRegistry("registry.example.com")
+            .withRepository("mirror/wiremock")
+            .withTag("custom");
+
+        assertThat(image.getCompatibleSubstituteFor()).isSameAs(compatibleImage);
+        assertThat(image.isCompatibleWith(compatibleImage)).isTrue();
+    }
+
     @Test
     void testPlainImage() {
         DockerImageName subject = DockerImageName.parse("foo");