Expose explicitly declared image compatibility

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

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");