Preserve tag in DockerImageName when both tag and digest are present

When parsing image names like "image:7.3.0@sha256:abcd", the tag was
previously discarded. This caused getVersionPart() to return the sha256
digest instead of the tag, breaking version-based feature checks in
modules like Kafka, Neo4j, Elasticsearch, etc.

Now getVersionPart() returns the tag when both are present, and a new
getDigest() method provides access to the sha256 digest. RemoteDockerImage
uses the digest for pulling when available. asCanonicalNameString()
correctly outputs "image:tag@sha256:hash" format.

Author: konstantinosGkilas

core/src/main/java/org/testcontainers/images/RemoteDockerImage.java

@@ -89,9 +89,10 @@ protected final String resolve() {
             final Instant startedAt = Instant.now();
             final Instant lastRetryAllowed = Instant.now().plus(PULL_RETRY_TIME_LIMIT);
             final AtomicReference<Exception> lastFailure = new AtomicReference<>();
+            String pullTag = imageName.getDigest() != null ? imageName.getDigest() : imageName.getVersionPart();
             final PullImageCmd pullImageCmd = dockerClient
                 .pullImageCmd(imageName.getUnversionedPart())
-                .withTag(imageName.getVersionPart());
+                .withTag(pullTag);
             final AtomicReference<String> dockerImageName = new AtomicReference<>();
 
             // The following poll interval in ms: 50, 100, 200, 400, 800....

core/src/main/java/org/testcontainers/utility/DockerImageName.java

@@ -88,8 +88,14 @@ public DockerImageName(String fullImageName) {
 
         if (remoteName.contains("@sha256:")) {
             String beforeDigest = remoteName.split("@sha256:")[0];
-            repository = beforeDigest.contains(":") ? beforeDigest.split(":")[0] : beforeDigest;
-            versioning = new Sha256Versioning(remoteName.split("@sha256:")[1]);
+            if (beforeDigest.contains(":")) {
+                repository = beforeDigest.split(":")[0];
+                String tag = beforeDigest.split(":")[1];
+                versioning = new Sha256Versioning(remoteName.split("@sha256:")[1], tag);
+            } else {
+                repository = beforeDigest;
+                versioning = new Sha256Versioning(remoteName.split("@sha256:")[1]);
+            }
         } else if (remoteName.contains(":")) {
             repository = remoteName.split(":")[0];
             versioning = new TagVersioning(remoteName.split(":")[1]);
@@ -156,16 +162,40 @@ public String getUnversionedPart() {
     }
 
     /**
-     * @return the versioned part of this name (tag or sha256)
+     * @return the versioned part of this name (tag or sha256). When both tag and digest are present,
+     *         the tag is returned.
      */
     public String getVersionPart() {
+        if (versioning instanceof Sha256Versioning) {
+            String tag = ((Sha256Versioning) versioning).getTag();
+            if (tag != null) {
+                return tag;
+            }
+        }
         return versioning.toString();
     }
 
+    /**
+     * @return the sha256 digest if present, or null
+     */
+    @Nullable
+    public String getDigest() {
+        if (versioning instanceof Sha256Versioning) {
+            return versioning.toString();
+        }
+        return null;
+    }
+
     /**
      * @return canonical name for the image
      */
     public String asCanonicalNameString() {
+        if (versioning instanceof Sha256Versioning) {
+            String tag = ((Sha256Versioning) versioning).getTag();
+            if (tag != null) {
+                return getUnversionedPart() + ":" + tag + "@" + versioning;
+            }
+        }
         return getUnversionedPart() + versioning.getSeparator() + getVersionPart();
     }
 

core/src/main/java/org/testcontainers/utility/Versioning.java

@@ -79,8 +79,20 @@ class Sha256Versioning implements Versioning {
 
         private final String hash;
 
+        @EqualsAndHashCode.Exclude
+        private final String tag;
+
         Sha256Versioning(String hash) {
+            this(hash, null);
+        }
+
+        Sha256Versioning(String hash, String tag) {
             this.hash = hash;
+            this.tag = tag;
+        }
+
+        String getTag() {
+            return tag;
         }
 
         @Override

core/src/test/java/org/testcontainers/utility/DockerImageNameCompatibilityTest.java

@@ -105,7 +105,9 @@ void testTagAndDigestImageIsCompatible() {
 
     @Test
     void testTagAndDigestImageWithRegistryIsCompatible() {
-        DockerImageName subject = DockerImageName.parse("registry.foo.com/repo:tag@sha256:1234abcd1234abcd1234abcd1234abcd");
+        DockerImageName subject = DockerImageName.parse(
+            "registry.foo.com/repo:tag@sha256:1234abcd1234abcd1234abcd1234abcd"
+        );
 
         assertThat(subject.isCompatibleWith(DockerImageName.parse("registry.foo.com/repo")))
             .as("registry.foo.com/repo:tag@sha256:... ~= registry.foo.com/repo")

core/src/test/java/org/testcontainers/utility/DockerImageNameTest.java

@@ -160,16 +160,24 @@ void testTagAndDigestStripsTagFromRepository() {
 
             assertThat(imageName.getRegistry()).isEqualTo("");
             assertThat(imageName.getUnversionedPart()).isEqualTo("myname");
-            assertThat(imageName.getVersionPart()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.getVersionPart()).isEqualTo("latest");
+            assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.asCanonicalNameString())
+                .isEqualTo("myname:latest@sha256:1234abcd1234abcd1234abcd1234abcd");
         }
 
         @Test
         void testTagAndDigestWithRepoPath() {
-            DockerImageName imageName = DockerImageName.parse("repo/myname:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
+            DockerImageName imageName = DockerImageName.parse(
+                "repo/myname:1.0@sha256:1234abcd1234abcd1234abcd1234abcd"
+            );
 
             assertThat(imageName.getRegistry()).isEqualTo("");
             assertThat(imageName.getUnversionedPart()).isEqualTo("repo/myname");
-            assertThat(imageName.getVersionPart()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.getVersionPart()).isEqualTo("1.0");
+            assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.asCanonicalNameString())
+                .isEqualTo("repo/myname:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
         }
 
         @Test
@@ -180,7 +188,18 @@ void testTagAndDigestWithRegistry() {
 
             assertThat(imageName.getRegistry()).isEqualTo("registry.foo.com:1234");
             assertThat(imageName.getUnversionedPart()).isEqualTo("registry.foo.com:1234/repo-here/my-name");
+            assertThat(imageName.getVersionPart()).isEqualTo("1.0");
+            assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.asCanonicalNameString())
+                .isEqualTo("registry.foo.com:1234/repo-here/my-name:1.0@sha256:1234abcd1234abcd1234abcd1234abcd");
+        }
+
+        @Test
+        void testDigestOnlyHasNoTag() {
+            DockerImageName imageName = DockerImageName.parse("myname@sha256:1234abcd1234abcd1234abcd1234abcd");
+
             assertThat(imageName.getVersionPart()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
+            assertThat(imageName.getDigest()).isEqualTo("sha256:1234abcd1234abcd1234abcd1234abcd");
         }
     }
 }